Markdown，你被嫌弃了

Markdown，你被嫌弃了

上周，Claude Code 团队的工程师 Thariq 发了一篇帖子，大意是：我们团队已经全面放弃 Markdown，转向 HTML 了。

评论区当场炸锅。有人说”Markdown 是程序员的圣经，你居然要革命？”也有人直接甩了一句——”过度工程化的又一个典型案例。”

但如果你仔细看完他的理由，你可能会和我一样，沉默几秒，然后默默打开自己那些超过 100 行的 Markdown 文件，开始反思。

Markdown 统治了十五年，谁给它判的”死刑”？

先说清楚一件事：没有人判 Markdown 死刑。

Markdown 从 2004 年诞生到今天，几乎垄断了开发者的文档世界。GitHub 用它，Notion 的底层在用它，你写博客用它，写 README 用它，甚至写周报都在用它。它的核心优势就四个字——所见即所想。不需要打开 Word，不需要纠结排版，敲几个井号和星号，文字就有了结构。

这套逻辑在”人写人读”的时代近乎完美。

但 2026 年的现实是：你的文档，越来越多时候不是写给人看的，而是写给 AI Agent 看的。

当 AI 成为你代码的第一读者，事情就变味了。

AI 最擅长”写” Markdown，却最怕”读” Markdown

这件事确实有点讽刺。

你让 ChatGPT、Claude、Gemini 输出任何内容，它们默认吐出来的就是 Markdown。加粗、列表、代码块，格式规规矩矩。看起来 Markdown 是 AI 的”母语”。

但问题在于，AI 生成 Markdown 很轻松，AI 解析 Markdown 却很头疼。

为什么？因为 Markdown 的设计哲学就是”怎么写都行”。加粗可以用 ** 也可以用 __，链接有三种写法，列表的缩进规则在不同解析器里表现不同。对人类来说，这叫灵活；对需要精确解析内容的 AI Agent 来说，这叫歧义。

打个比方：Markdown 像普通话，各地口音都能听懂，但机器做语音识别时，口音越重错误率越高。HTML 像标准化的电报编码——死板，但每个符号都有唯一确定的含义。

Thariq 在帖子里说了一个细节：团队超过 100 行的 Markdown 文件，几乎没有人会真的读完。不是因为内容不好，是因为纯文本的平铺直叙，实在太考验注意力了。换成 HTML 之后，可以加导航栏、分标签页、插交互图表，同事的阅读完成率明显上升了。

人都读不完的文档，你指望 AI Agent 完美理解？

三个真实的推力，把 Markdown 推下了神坛

Thariq 不是心血来潮。整个 Claude Code 团队转向 HTML，背后有三个实打实的技术推力。

第一推力：结构化需求。

AI Agent 要修改一份文档里的某个段落，首先得精确定位那个段落在哪。HTML 天然就是一棵 DOM 树——每个元素都有标签、有层级、有属性，定位起来就像在地图上找经纬度。

Markdown 呢？它的结构是”隐含”的。一个二级标题下面跟着的内容，到底归属这个标题还是下一个标题？不同的解析器可能给出不同答案。对人来说无所谓，对 AI 来说，这种模糊性是灾难的起点。

第二推力：表达力的天花板。

当 AI 输出不再只是文字，而是需要直接渲染成可交互的界面时，Markdown 的能力就捉襟见肘了。

Thariq 的团队用 HTML 生成的东西，已经远超”文档”的范畴：带滑块的参数调节面板、可拖拽的任务看板、带颜色标注和严重程度分级的代码审查报告。这些东西要用 Markdown 来做？你试试用纯文本画一个滑块出来。

他甚至给每个 PR 都附上一份 HTML 格式的代码审查报告——颜色标注、内联批注、严重程度分级，review 效率直接翻倍。如果这件事用 Markdown 做，你能得到什么？一堆嵌套的引用块和手动对齐的表格。

第三推力：转换链条上的损耗。

Markdown 到最终展示，中间要经过一条链路：MD 源文件 → 解析器转 HTML → 浏览器渲染。每经过一步，信息就可能丢失或变形。不同的 Markdown 解析器（CommonMark、GFM、Pandoc）对同一份文件的渲染结果，能差出十万八千里。

HTML 不需要这条链路。写出来是什么样，浏览器显示就是什么样。所写即所得，没有中间商赚差价。

这也是为什么 Notion 早就在底层放弃了纯 Markdown，转向了 Block 结构。它们面对的问题和 Claude Code 一样：当内容的消费者不仅仅是人，而是包含了程序和 AI 时，”所见即所想”的朴素哲学就不够用了。

但别急着把 Markdown 扔进垃圾桶

看到这里，如果你打算明天就把所有项目的文档从 MD 迁移到 HTML，先等一下。

Thariq 自己也承认，HTML 有真实的代价：

生成速度慢了 2-4 倍。 HTML 结构复杂、标签冗长，AI 生成同样内容的 HTML 版本需要更多 token，速度明显下降。

版本控制是个噩梦。 这是 Thariq 原话中说的”HTML 最大的缺点之一”。git diff 一个 Markdown 文件，改了哪个字一目了然；git diff 一个 HTML 文件，满屏的标签噪音让你根本看不出实质变更在哪。

学习曲线。 不是每个开发者都熟悉 HTML/CSS。后端工程师写 Go、写 Python 很溜，让他调一个 flex 布局可能要折腾半天。

所以，这件事的正确姿势不是”非此即彼”，而是看你的场景。

一个简单的判断框架：你的文档谁在读？

场景	推荐格式	原因
日常笔记、个人知识库	Markdown	速度快、书写流畅、不需要复杂渲染
项目 README、API 文档	Markdown	生态成熟，GitHub 原生支持
AI Agent 间的通信协议	HTML / JSON	需要精确的结构化，消除解析歧义
AI 生成的交互式报告	HTML	可嵌入图表、控件、导航
需要协作审阅的设计文档	HTML	阅读体验好，审阅效率高

核心判断逻辑就一句话：你的内容，主要是”人读”还是”机读”？

如果主要是人来写、人来读——Markdown 仍然是最佳选择，它的简洁性在这个场景里依然无可替代。

如果主要是 AI 来生成、AI 来消费，或者需要渲染成可交互的产物——HTML 正在成为更合理的选择。

别折腾的归别折腾，该升级的别犹豫。

格式之争的底层，是”谁是第一读者”的变迁

回到最开始那个令人震动的消息：Claude Code 团队全面转向 HTML。

这件事真正的信号，不是”HTML 比 Markdown 好”。这个结论太粗暴，也不准确。

真正的信号是：我们正在进入一个”机器是第一读者”的时代。

纸质办公时代，文档的第一读者是打印出来看的人，所以 Word 统治了一切。协作时代，文档的第一读者是屏幕前的队友，所以 Markdown 和 Notion 崛起了。而现在，AI Agent 时代，文档的第一读者越来越多地变成了机器——你的 AI 编程助手、你的自动化流水线、你的智能审查工具。

当第一读者变了，文档的最优格式自然要跟着变。

这不是技术洁癖，不是过度工程化，也不是为了酷炫。这是工具链在生产力压力下的自然进化。

十年前你从 Word 切换到 Markdown 的时候，也没觉得是在”革命”——你只是选了一个更适合当时工作方式的工具。

现在，同样的事情又发生了一次而已。

只不过这一次，你需要考虑的不仅是自己读着舒不舒服，还有你的 AI 搭档读着顺不顺畅。

毕竟，当你和 AI 合写代码的时间已经超过了和同事的时间，你最常用的文档格式，也该跟着你的主要协作对象走了。