md-preview：在侧边窗格中进行 Claude Code Markdown 预览

md-preview 是一款 Claude Code Markdown 预览社区插件，作者是 Hamza Zafar（hamzafer），属于他的 claude-code-mods 合集。它为 Claude Code 提供 Markdown 预览：当 Claude 写入或编辑 .md、.mdx 或 .markdown 文件时，会弹出提示 README.md changed · /md to preview，而 /md 会在对话旁打开一个窗格，按照 GitHub 的显示方式渲染该文件。

窗格中有 Prev、Next、Before、Render、Text、Browser 和 Close 按钮，每个按钮都有快捷键（p、n、b、r、t、o、q）。n 和 p 键可以在本次会话中改动过的 Markdown 文件之间切换。b 会把文件在本轮第一次编辑之前的样子和当前内容并排显示，最近一次编辑改动的区块会带有一条绿色竖条。/md compare <a> <b> 会把两个文件并排显示，o 或 /md open 会在你自己的浏览器中打开同一页面。

页面的绘制方式取决于你的环境。在支持图片的终端（Ghostty、iTerm2、WezTerm 或 kitty，不经过 tmux）中，并且安装了 Chrome 或某个 Chromium 浏览器时，页面会被绘制成 PNG 并显示在窗格中。否则，窗格会显示文本视图，用终端颜色呈现标题、列表、表格和代码块。清单文件中没有写明最低 Claude Code 版本。

录屏中，我们在小型演示项目里启动加载了该插件的 Claude Code，并运行 /md README.md。命令会回复按键提示（n/p: next/previous · b: before | after · o: browser · r: render again · t: page/text · q: close），随后输入框上方打开一个带边框的窗格。第一行是按钮，第二行显示 README.md 1/1，下面以文本视图显示项目的 README：标题 demo-app 和一行 "A tiny demo app. Run it with npm start."，其中的代码片段带有颜色。演示所用的终端无法显示图片，因此显示的是文本视图，而不是渲染后的页面。

使用安装区块中的任意一种方式；它们都直接从作者自己的插件市场安装。安装后运行 /reload-plugins 或开启新会话，然后使用 /md。

插件由一个函数钩子模块 hooks/register.tsx，加上一个小型 Markdown 解析器（hooks/md.ts）和一个 HTML 页面生成器（hooks/page.ts）组成。tool.call 钩子会在对 Markdown 路径执行 Write、Edit 或 MultiEdit 调用之前读取该文件，然后让调用照常执行，并原样返回结果。以下是 GitHub 渲染器，来自 hooks/register.tsx：

const repo = await repoOf($, dir)
if (!repo) return null // not in a GitHub repo: the Markdown stays on this machine
const r = await $.process
  .run(['gh', 'api', '-X', 'POST', '/markdown', '--input', '-'], { stdin: JSON.stringify({ text: md, mode: 'markdown', context: repo }), timeoutMs: GH_TIMEOUT_MS })
  .catch(() => null)

repoOf 通过 git remote -v 查找 GitHub remote。如果 gh 失败，GitHub 渲染会暂停一分钟，期间使用内置渲染器。HTML 会写入 $TMPDIR/md-preview/，并通过一个简短的 sh 脚本用无头 Chrome 绘制，每次只绘制一个，绘制结果按内容缓存。Claude 编辑过的文件会在这一轮结束后于后台绘制，所以 /md 打开时通常页面已经绘制好了。

/config 中没有任何选项。所有操作都通过命令和窗格按键完成：/md 打开最近的文件，/md <path> 打开任意 Markdown 文件，/md compare <a> <b> 对比两个文件，/md open 在浏览器中打开。如果 /md 这个名字已被其他命令占用，插件会改为注册 /mdview。若要修改 Chrome 路径列表（CHROMES）、保留的文件数（MAX_FILES）或缓存大小（CACHE_SIZE）等限制，请编辑 register.tsx 顶部的常量。

在运行之前，我们读过了插件可以执行的每一个文件：plugin.json、hooks/hooks.json、hooks/register.tsx、hooks/md.ts、hooks/page.ts、类型声明以及测试。没有 package.json、安装脚本、二进制文件或打包后的代码，我们也没有发现隐藏字符或零宽字符。

• **网络：**没有直接请求。存在 GitHub remote 且 gh 已登录时，Markdown 文本会通过 gh api 发送到 GitHub 的 /markdown API（register.tsx:592-594），无需额外选择启用。大于约 390 KB 的文件在本地渲染。渲染后的页面由无头 Chrome 加载，其 Content-Security-Policy 允许加载任意主机的图片（page.ts:97），因此 Markdown 文件中的远程图片会在绘制页面时被获取。Markdown 中的脚本无法运行。
• 进程：git ls-files 和 git remote -v（register.tsx:386、607），gh api（593），带固定脚本的 sh -c，用于启动无头 Chrome，并且只停止它自己启动的 Chrome（49-67、675），以及浏览器按钮使用的 open 或 xdg-open（788）。
• **文件写入：**只写入 $TMPDIR/md-preview/（页面 HTML、PNG 分块和一次性 Chrome 配置文件）。不会写入 ~/.claude、设置、shell 配置文件、LaunchAgents 或 git 钩子。
• **文件读取：**Claude 编辑的 Markdown 文件、你指定的文件，以及在一轮对话的第一条 shell 命令之前，通过 git ls-files 读取仓库中最多 200 个 Markdown 文件。
• 环境变量：HOME、TMPDIR、TMUX、TERM_PROGRAM 和 TERM。它们不会被发送到任何地方。
• **守护进程、遥测、提示词注入：**都没有。它不会向提示词或工具结果中添加任何文本。
• 拦截：tool.call 钩子只是观察者。它等待调用完成并原样返回结果。validate 把它标记为没有 .catch 的拦截钩子；一轮对话的第一次 shell 调用会等待 Markdown 快照完成，而快照只读取文件。
• **外部依赖：**渲染视图需要 Chrome、Chromium、Edge 或 Brave，以及支持图片的终端，gh 可选。这些都是可选的；退而求其次会使用文本视图。
• **许可证：**MIT，仓库根目录有 LICENSE 文件。

claude plugin validate 没有报告任何错误或警告，作者的 26 个测试在 Claude Code 2.1.291 上全部通过。

已在 macOS 上使用 Claude Code 2.1.291 检查（validate、测试和录屏）。如果窗格的表现不符合预期：

• 提示 /md 未知：检查 /plugin 是否显示 md-preview 已加载，或者试试 /mdview。
• 看到的是文本而不是页面：你的终端无法显示图片、你在 tmux 中，或者没有找到 Chrome。解决后按 r，或按 t 切换视图。
• "Chrome could not draw the page"：按 r 重试。插件不会自动重试。
• 文件改动后没有弹出提示：只跟踪 Markdown 路径，并且只有在 git 仓库中才能察觉 shell 写入。
• 窗格显示 built-in 而不是 GitHub：文件不在 GitHub 仓库中、gh 未登录，或者文件大于约 390 KB。