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.md
Add a file to a running server
python3 -m md_preview_and_annotate --add another.md --port 3031
Add 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