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

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