最近读到 Anthropic 官方博客里那篇《Using Claude Code: The unreasonable effectiveness of HTML》，我第一反应不是“HTML 要取代 Markdown 了”，而是突然意识到：我之前把文档格式想得太单一了。

我过去默认会把技术笔记、命令手册、使用记录都写成 Markdown。原因很简单，Markdown 好写、好改、好复制，也很适合放在目录里长期保存。像 README、排查记录、命令备忘录这种东西，Markdown 几乎是下意识选择。它不需要解释，也不需要设计，打开就能写。

但这次我刚好做了一个很小的对照实验。

我先整理了一份《Code CLI 四大工具快捷命令手册》的 Markdown 文档，把 Codex CLI、Claude Code CLI、Gemini CLI、OpenCode CLI 的常用命令放在一起。那份文档其实已经够用了，结构清楚，搜索也方便，后面如果 CLI 升级了，继续改 Markdown 也很顺手。

后来我又根据同一份内容生成了一版 HTML 笔记。内容没有本质变化，但阅读感觉完全变了。HTML 版本有顶部总览，有工具选择流程图，有命令搜索框，有复制按钮，也有分区导航。它不像一份“源文档”，更像一个可以直接打开使用的小工具。

如果要把这个对照放进博客里，我反而不想截一张特别长的图。长截图看起来完整，但读者其实很难从里面抓住重点。我更想放一张 HTML 版首屏或者“搜索框 + 命令矩阵”的局部截图，再把两份完整文件放在文末附件处。这样正文里能看到差异，真感兴趣的人也可以自己点开看完整版本。

这时候我才理解 Anthropic 那篇文章里说的那种“HTML 的不讲道理地有效”。不是因为 HTML 比 Markdown 更高级，而是因为当一份文档的目标从“保存内容”变成“帮助人快速理解和使用”时，HTML 能做的事情多很多。

Markdown 更像我写给未来自己的底稿。它适合沉淀，适合 diff，适合让 AI 或人继续改。HTML 更像把这份底稿重新排版成一张工作台。尤其是命令手册这种东西，我真正需要的不是从头读到尾，而是在某个场景下快速找到能用的那条命令。这个时候，搜索、导航、折叠、复制按钮这些小东西，比多写几段解释有用得多。

所以读完那篇文章以后，我对 Markdown 的看法没有变得悲观。它仍然会是我默认的写作格式。只是我会更清楚地区分：有些文档是拿来维护的，有些文档是拿来阅读和操作的。前者 Markdown 很合适，后者 HTML 可能更合适。

这也让我对 AI 生成文档有了一个新的想法。以前我会让 AI 生成 Markdown，因为它最省事，也最容易继续编辑。但如果目标是做一份真正会反复打开查询的材料，只停留在 Markdown 可能有点可惜。现在的模型已经能把同一份内容转成可读性更好的 HTML 页面，这一步成本其实不高。

以后我可能会把这变成一个固定流程：先用 Markdown 写清楚内容，再在需要的时候生成一份 HTML 阅读版。Markdown 负责沉淀，HTML 负责使用。不是谁替代谁，而是一个当源稿，一个当成品。

这次那两份 Code CLI 手册就是一个挺好的提醒。很多时候，文档不是写完就结束了。真正的问题是：下次我需要它的时候，它能不能让我更快找到答案。

参考阅读： Using Claude Code: The unreasonable effectiveness of HTML