mdpreview

mdpreview — Markdown のプレビューと注釈

Catppuccin Mocha／Latte のライブリロード対応 Markdown ビューアーです。複数のタブをサポートし、Google ドキュメント風の余白注釈を表示します。

正規リポジトリ：github.com/tdimino/dabarat。クローンするか、md_preview_and_annotate が PYTHONPATH に含まれていることを確認してください。

クイックスタート

# 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

起動中のサーバーにファイルを追加する

python3 -m md_preview_and_annotate --add another.md --port 3031

CLI から注釈を追加する（サーバー不要）

python3 -m md_preview_and_annotate --annotate file.md \
  --text "RPL §235-b" --author "Claude" --comment "Cite the specific subsection"

サイドカー JSON（file.md.annotations.json）に直接書き込みます。ライブビューアーは次の 500ms のポーリングサイクルで変更を反映します。

機能

機能	詳細
ライブリロード	500ms 間隔でポーリングし、ファイルの保存時に自動更新します
複数タブ	複数の .md ファイルを開き、タブを切り替えたり、実行中に追加・閉じたりできます
タブの再利用	サーバーの実行中に新しいファイルを起動すると、タブとして追加されます
注釈	作成者バッジ（人間／AI）付きの右余白コメント吹き出し
スレッド形式の返信	任意の注釈にインラインで返信できます
ブックマーク	~/.claude/bookmarks/ と INDEX.md にグローバル保存されます
サイドカー JSON	注釈はソースファイルと同じ場所にある file.md.annotations.json に保存されます
ファイルのタグ付け	コマンドパレットで # プレフィックスを使って、7 つの定義済みタグとカスタムタグを設定できます
コマンドパレット	Cmd+K／Ctrl+K でコマンド、タブ、最近使ったファイルにすばやくアクセスできます
Catppuccin	Mocha（ダーク）／Latte（ライト）の完全なテーマと 26 個の CSS 変数
タイポグラフィ	見出しは Cormorant Garamond、本文は DM Sans、コードは Victor Mono
サイドバー TOC	スクロール位置に追従する、サイズ変更可能な目次
コードのハイライト	Catppuccin のシンタックステーマを使った highlight.js
Chrome --app	ネイティブアプリのような操作感の、フレームレスな Chrome ウィンドウで開きます
ファイル間リンク	ローカルの .md リンクはページ遷移せず、新しいタブで開きます

注釈システム

注釈を対話的に作成するには、ビューアー内でテキストを選択します。フローティングボタンが表示されたら、右側の余白にあるコメントフォームに入力してください。

プログラムから注釈を作成する場合（例：Claude Code から）は、--annotate CLI フラグを使います。実行中のサーバーは不要で、サイドカー JSON に直接書き込みます。

• 人間の作成者 — 青色の名前バッジ
• AI の作成者 — ロボットアイコン付きのモーブ色の名前バッジ
• 操作 — 解決（取り消し線の切り替え）または削除（ゴミ箱アイコン）。ホバーすると表示されます
• 永続化 — サイドカー JSON ファイルに保存され、ビューアーの更新時またはファイルのポーリング時に自動読み込みされます

サイドカー JSON スキーマ

{
  "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 エンドポイント

エンドポイント	メソッド	用途
/api/content?tab=<id>	GET	タブの Markdown コンテンツ
/api/tabs	GET	開いているタブの一覧
/api/annotations?tab=<id>	GET	タブの注釈
/api/tags?tab=<id>	GET	タブのタグ
/api/add	POST	新しいファイルのタブを開く
/api/close	POST	タブを閉じる
/api/annotate	POST	注釈を作成する
/api/resolve	POST	注釈の解決状態を切り替える
/api/reply	POST	スレッド形式の返信を追加する
/api/delete-annotation	POST	注釈を削除する
/api/tags	POST	タグを追加／削除する