mdpreview — Markdown Preview & Annotate
Catppuccin Mocha/Latte live-reloading Markdown viewer with multi-tab support and Google Docs-style margin annotations.
Canonical repo: github.com/tdimino/dabarat. Clone it or ensure md_preview_and_annotate is on your PYTHONPATH.Quick Start
# Preview one or more files
python3 -m md_preview_and_annotate file.md [file2.md ...] --port 3031
# If not installed globally, run from the cloned repo:
python3 ~/Desktop/Programming/md-preview-and-annotate/md_preview_and_annotate/__main__.py file.mdAdd a file to a running server
python3 -m md_preview_and_annotate --add another.md --port 3031Add an annotation from CLI (no server needed)
python3 -m md_preview_and_annotate --annotate file.md \
--text "RPL §235-b" --author "Claude" --comment "Cite the specific subsection"This writes directly to the sidecar JSON (file.md.annotations.json). The live viewer picks it up on the next 500ms poll cycle.
Features
| Feature | Details |
|---|---|
| Live reload | 500ms polling, auto-refreshes on file save |
| Multi-tab | Open multiple.md files, switch tabs, add/close at runtime |
| Tab reuse | Launching a new file while the server is running adds it as a tab |
| Annotations | Right-margin comment bubbles with author badges (human/AI) |
| Threaded replies | Reply to any annotation inline |
| Bookmarks | Global persistence to ~/.claude/bookmarks/ with INDEX.md |
| Sidecar JSON | Annotations persisted in file.md.annotations.json alongside source |
| File tagging | 7 predefined + custom tags via command palette # prefix |
| Command palette | Cmd+K / Ctrl+K for quick access to commands, tabs, and recent files |
| Catppuccin | Full Mocha (dark) / Latte (light) theme with 26 CSS variables |
| Typography | Cormorant Garamond headings, DM Sans body, Victor Mono code |
| Sidebar TOC | Resizable table of contents with scroll-spy |
| Code highlighting | highlight.js with Catppuccin syntax theme |
| Chrome --app | Opens in frameless Chrome window for native feel |
| Cross-file links | Local .md links open in new tabs instead of navigating away |
Annotation System
To create annotations interactively, select text in the viewer — a floating button appears, then fill in the comment form in the right gutter.
To create annotations programmatically (e.g., from Claude Code), use the --annotate CLI flag. This requires no running server — it writes directly to the sidecar JSON.
- Human authors — blue name badge
- AI authors — mauve name badge with robot icon
- Actions — resolve (toggle strikethrough) or delete (trash icon), revealed on hover
- Persistence — sidecar JSON file, auto-loaded on viewer refresh or file poll
Sidecar JSON Schema
{
"version": 1,
"tags": ["draft", "research"],
"annotations": [
{
"id": "a1b2c3",
"anchor": { "text": "selected phrase", "heading": "", "offset": 0 },
"author": { "name": "Claude", "type": "ai" },
"created": "2026-02-12T15:30:00+00:00",
"body": "Comment text here",
"resolved": false,
"replies": []
}
]
}API Endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/api/content?tab=<id> | GET | Markdown content for a tab |
/api/tabs | GET | List open tabs |
/api/annotations?tab=<id> | GET | Annotations for a tab |
/api/tags?tab=<id> | GET | Tags for a tab |
/api/add | POST | Open a new file tab |
/api/close | POST | Close a tab |
/api/annotate | POST | Create an annotation |
/api/resolve | POST | Toggle annotation resolved state |
/api/reply | POST | Add a threaded reply |
/api/delete-annotation | POST | Delete an annotation |
/api/tags | POST | Add/remove a tag |