mdpreview

mdpreview — Markdown 预览与批注

支持实时重新加载、多标签页的 Catppuccin Mocha/Latte Markdown 查看器，并提供 Google Docs 风格的页边批注。

规范仓库：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
侧边栏目录	可调整大小并带有滚动定位功能的目录
代码高亮	使用 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	添加或移除标签