夜雨聆风
AI生成的技术文档,为什么要从Markdown走向HTML
AI生成的技术文档，为什么要从Markdown走向HTML？
AI现在写技术文档动辄几千字甚至上万字，纯文本或终端滚动阅读几乎没人愿意看。Markdown是极好的中间态，但HTML才是面向读者的最终态。
Markdown vs HTML：AI圈最新一轮“世子之争”
最近，AI圈刮起一股HTML vs Markdown的热议。导火索之一是Anthropic/Claude团队有人公开推动HTML输出，并带动了大量讨论和benchmark。有人测试发现，在复杂文档场景中，HTML输出不仅阅读体验更好，还在某些工作流里更省token、更高效，人类读者也更爱看。
这场讨论再次把两者优劣摆上台面：
•Markdown：轻量、易读、机器友好、token消耗低、方便编辑和版本控制。它是AI与人类对话的天然桥梁——你用Markdown和AI交流，AI也用Markdown回复你。对话和迭代阶段，HTML太重，不合适。
•HTML：表现力极强，能直接实现侧边栏目录、交互折叠、图表、时间线、卡片、警告框等元素，大幅提升阅读效率和沉浸感，尤其适合技术文档、代码审查、流程图、PRD等“最终消费”场景。
核心共识是：两者不是取代关系，而是分层协作。
Markdown是生产与加工的中间态，HTML是发布与阅读的最终态。
同样一段## 标题，在GitHub、公众号、Notion、小红书渲染效果各不相同。而HTML能一次生成、到处一致——发给团队、发公众号、发知乎、发Substack，都保持统一专业样式，无需反复适配。
最后一公里的工程化利器
从写完Markdown到真正美观、可直接发布的HTML，这段“最后一公里”曾经是痛点。现在已经有了成熟解决方案：
LeopardNeuro（兰若）AI编辑器 把这件事做得特别极致实用：
•内置几十种专业级 Markdown 转 HTML Skills，覆盖多种风格和行业场景。
•生成Markdown后，一键切换HTML风格，无需上网找模板或手动调样式。
•支持自由下载和扩展 Skills，随时个性化你的输出模板。
•自动生成侧边栏目录、图表、时间线、卡片布局、醒目警告框等现代文档元素，一个HTML单文件即可发给团队或直接发布。
这完美契合了Claude团队推动HTML输出后的社区需求：让AI生成的内容能快速变成高质量、可直接消费的最终形态。
推荐工作流（重度AI用户都在这么做）
1.正文层：用纯Markdown与AI高效迭代、修改、保存。
2.呈现层：通过LeopardNeuro一键转成精美HTML（切换不同Skills适配不同平台）。
3.视觉层：封面、卡片、海报等走独立模板化生成。
特别适合技术文档、产品PRD、内部知识库、长文博客、公众号、知乎、Mirror、Substack等场景。
结语
Anthropic/Claude团队的HTML尝试再次证明：AI内容生产正在从“能写”走向“好看、好读、可直接交付”。Markdown不会消失，但HTML正在成为越来越多场景下的最终选择。
LeopardNeuro 正好卡在这个关键节点，提供几十种现成Skills，让你不用自己造轮子，就能把AI写的Markdown秒变专业HTML文档。专注内容创作，剩下的交给工具。
这场“世子之争”最终会和解——Markdown负责高效生产，HTML负责优雅呈现，而好的工具让切换变得丝滑。
如果你也在用AI批量生产内容，推荐试试LeopardNeuro的Markdown转HTML能力。生成Markdown → 选Skill → 下载精美HTML，整个流程非常顺畅。
你目前更偏好Markdown还是HTML输出？或者已经在用哪些Skills？欢迎分享你的场景，我可以帮你优化具体工作流。🚀
—— 让AI写得更多，让读者看得更好。
https://weixin.qq.com/sph/AXXLNsYtR
Anthropic/Claude团队写的原文：
使用 Claude Code：HTML 的惊人效果
Markdown 已成为 agent 与我们沟通时使用的主流文件格式。它简单、可移植、具备一定的富文本能力，且易于编辑。Claude 甚至已经相当擅长在 markdown 文件中用 ASCII 绘制图表。
但随着 agent 的能力越来越强，我开始觉得 markdown 成了一种限制性格式。我发现超过一百行的 markdown 文件很难读下去。我想要更丰富的可视化效果、色彩和图表，并且希望它们能轻松分享。
我也越来越不自己编辑这些文件了，而是把它们当作规格说明、参考文件、头脑风暴输出等用途。当我确实需要编辑时，通常也是让 Claude 来改——这反而消除了 markdown 最大的优势之一。
我开始倾向于用 HTML 替代 Markdown 作为输出格式，Claude Code 团队中的其他人也越来越普遍地这样做。原因如下。
（如果你想先看一些示例，可以访问 https://thariqs.github.io/html-effectiveness，但记得回来看完为什么。）
为什么选择 HTML？
信息密度
与 markdown 相比，HTML 可以传达更丰富的信息。它当然能处理简单的文档结构（如标题和格式），但它还能表示各种其他信息：
•表格数据 —— 使用表格
•设计数据 —— 使用 CSS
•插图 —— 使用 SVG
•代码片段 —— 使用 script 标签
•交互 —— 使用 HTML 元素 + JavaScript + CSS
•工作流 —— 使用 SVG 和 HTML
•空间数据 —— 使用绝对定位和画布
•图片 —— 使用图片标签
我甚至可以说，几乎没有任何 Claude 能读取的信息是你无法用 HTML 高效表达的。这使得 HTML 成为模型向你传达深度信息、供你审阅的一种极其高效的方式。
我发现，如果做不到这一点，模型可能会在 markdown 中做一些低效的事情，比如 ASCII 图表，或者我最喜欢的——用 unicode 字符来模拟颜色，就像 Claude Code 中的这个截图一样。
视觉清晰度与易读性
随着 Claude 能处理越来越复杂的工作，它也在编写越来越庞大的规格说明和计划。实际上，我发现我往往不会真正阅读超过 100 行的 markdown 文件，而且我肯定无法让组织中的其他人去读它。
但 HTML 文档读起来容易得多。Claude 可以在视觉上优化结构，使其非常适合通过标签页、插图、链接等方式导航。它甚至可以做到移动端响应式，让你根据不同的设备以不同方式阅读。
易于分享
Markdown 文件很难分享，因为大多数浏览器不能很好地原生渲染它们。你通常需要把它们作为附件添加到邮件或消息中。
而使用 HTML，只要你上传文件（例如上传到 S3），就可以轻松分享链接。你的同事可以在任何地方打开它，并轻松引用。
别人真正阅读你的规格说明、报告或 PR 总结的概率，如果是 HTML 格式会高得多。
双向交互
HTML 可以让你与文档进行交互。例如，你可以要求它添加滑块或旋钮来调整设计，或者让你调整算法中的不同选项来观察效果。你还可以让它提供复制按钮，将这些更改复制为 prompt，粘贴回 Claude Code。
更多关于这种双向交互的示例，请阅读我的 playgrounds 文章：https://x.com/trq212/status/2017024445244924382
数据摄取
为什么要用 Claude Code 来制作 HTML 文件，而不是用 ClaudeAI 或 Claude Design？最大的原因之一是 Claude Code 可以摄取的上下文量。
例如，在写这篇文章时，我让 Claude Code 读取我的代码文件夹，找到我生成的所有 HTML 文件，分组归类，然后制作一个包含每种类型图表的 HTML 文件。你在本文中看到的图表就是直接由此产生的。
除了文件系统，Claude Code 还可以通过你的 MCP（如 Slack、Linear 等）、你的浏览器（配合 Chrome 中的 Claude）、你的 git 历史等获取更多上下文。
它让人愉悦
用 Claude 制作 HTML 文档更有趣，让我感觉更投入、更有参与感——这本身就足够了。
如何开始
我有点担心人们读了这篇文章后会把它变成一个 /html skill 之类的东西。虽然这可能有一定价值，但我想强调的是，你不需要做太多事情就能让 Claude 做到这一点。你只需要对它说”做一个 HTML 文件”或”做一个 HTML artifact”。
关键在于知道你想要 artifact 做什么，以及你打算如何使用它。随着时间的推移，你可能会制作一个 skill，但现在我建议直接从零开始 prompt，以掌握在不同场景下如何使用它。
使用场景
为了让这更具体，我为不同的使用场景制作了许多 HTML 文件。你可以在这里查看全部：https://thariqs.github.io/html-effectiveness/，以下是概览。
规格说明、规划与探索
HTML 是 Claude 深入问题的丰富画布。当我开始处理一个问题时，我不会只做一个简单的 markdown 计划，而是期望制作一个 HTML 文件网络。例如，我可能会先让 Claude Code 进行头脑风暴，创建一些不同选项的探索。然后我会要求它进一步展开其中一个方向，可能制作一些 mockup 或代码片段。最后，当我感觉良好时，我会让它编写一个实现计划。当我对计划满意时，我会创建一个新的 session，传入所有这些文件让它实现。
在验证时，我也会让验证 agent 读取这些文件，这样它就能对需求有更广泛的上下文。
示例 Prompt：
我不确定 onboarding 界面应该采用什么方向。生成 6 种截然不同的方案——在布局、风格和信息密度上有所变化——将它们以网格形式放在一个 HTML 文件中，方便我并排比较。为每个方案标注其权衡取舍。
创建一个详尽的实现计划 HTML 文件，确保包含一些 mockup、展示数据流，并添加我可能需要审查的重要代码片段。让它易于阅读和理解。
适用场景：
•探索实现某功能的其他方式
•探索多种视觉设计
代码审查与理解
代码在 Markdown 文件中很难阅读。但使用 HTML，我们可以渲染 diff、注释、流程图、模块结构等。用它来理解 agent 编写的代码、进行代码审查，或向审查你 PR 的人解释代码。我发现这通常比默认的 GitHub diff 视图效果更好，现在我提交的每个 PR 都会附带一个 HTML 代码解释文件。
示例 Prompt：
帮我审查这个 PR，创建一个描述它的 HTML artifact。我对 streaming/backpressure 逻辑不太熟悉，所以请重点讲解这部分。渲染实际的 diff，在页边距添加内联注释，按严重程度对发现的问题进行颜色编码，以及任何其他有助于传达概念的内容。
适用场景：
•创建 PR
•审查 PR
•理解代码中的某个主题
设计与原型
Claude Design 基于 HTML，因为 HTML 在设计方面极具表现力，即使你的最终交付物不是 HTML。Claude 可以用 HTML 勾勒设计，然后用你选择的语言（React、Swift 等）实现。
你还可以制作交互原型，比如动画、动作等。考虑让 Claude 制作滑块、旋钮等，来精确调优你想要的效果。
示例 Prompt：
我想原型化一个新的结账按钮，点击时播放一个弹跳动画，然后快速变为紫色。创建一个包含多个滑块和选项的 HTML 文件，让我可以尝试这个动画的不同参数，给我一个复制按钮来复制效果好的参数组合。
适用场景：
•构建设计系统 artifact
•调整组件
•可视化组件库
•制作令人愉悦的动画原型
报告、研究与学习
Claude Code 非常擅长综合多个数据源的信息，并将其转化为可读性强的报告。你可以让 Claude 搜索你的 Slack、代码库、git 历史、互联网等，然后为你自己、为领导层、为团队生成极其易读的报告。
你可以将其组织成一个长 HTML 文档、一个交互式讲解页面，甚至是一个幻灯片/deck。让 Claude 使用 SVG 绘制图表来帮助可视化。
例如，在我写关于 prompt caching 的文章时，我让 Claude 在阅读 git 历史后，准备一份关于我们所有 prompt caching 变更的深度研究 HTML 文件供我阅读。
示例 Prompt：
我不理解我们的限流器实际上是如何工作的。阅读相关代码，生成一个 HTML 讲解页面：包含令牌桶流程的图表、3-4 个带注释的关键代码片段，以及底部的”注意事项”部分。优化为让人读一遍就能理解。
适用场景：
•总结某个功能的工作原理
•向我解释一个概念
•给老板的每周状态报告
•给领导层的事故报告
•SVG 插图、流程图、技术图表等
自定义编辑界面
有时很难纯粹在文本框中描述你想要的东西。在这种情况下，我会让 Claude 为我正在处理的具体内容构建一个一次性编辑器。不是一个产品，也不是一个可复用的工具，而是一个单一的 HTML 文件，专门为这一份数据量身定制。
诀窍是始终以导出功能结尾：一个”复制为 JSON”或”复制为 prompt”的按钮，将我在 UI 中所做的操作转换回可以粘贴到 Claude Code 中的内容。
示例 Prompt：
我需要重新排列这 30 个 Linear 工单的优先级。给我做一个 HTML 文件，每个工单是一个可拖拽的卡片，分布在 Now / Next / Later / Cut 列中。按你的最佳判断预先排序。添加一个”复制为 markdown”按钮，导出最终排序结果，并为每个分组附上一行理由。
这是我们的功能开关配置。为它构建一个表单编辑器，按区域分组，显示依赖关系，如果我启用了一个前置条件未开启的开关，给出警告。添加一个”复制 diff”按钮，只输出变更的键。
我在调优这个系统 prompt。做一个并排编辑器：左侧是可编辑的 prompt，变量槽位高亮显示；右侧是三个示例输入，实时渲染填充后的模板。添加字符/Token 计数器和复制按钮。
适用场景：
•重新排序、分类或分桶任何内容（工单、测试用例、反馈）
•编辑结构化配置（功能开关、环境变量、JSON/YAML 带约束）
•调优 prompt、模板或文案，带实时预览
•管理数据集：批准/拒绝行、标记示例、导出选择结果
•注释文档、转录稿或 diff，并导出注释
•选择难以用文本表达的值：颜色、缓动曲线、裁剪区域、cron 表达式、正则表达式
常见问题
我一直在向很多人介绍我如何转向使用 HTML，也看到了一些反复出现的问题。
它的 Token 效率不是更低吗？
虽然 markdown 通常使用更少的 token，但我发现 HTML 更强的表现力以及我更有可能去阅读它，意味着我总体上获得了更好的输出。在 Opus 4.7 的 100 万上下文窗口下，增加的 token 使用量在上下文窗口中并不明显。
你现在什么时候用 markdown？
老实说，我几乎在所有场景下都停止使用 markdown 了，但我可能属于 HTML 最大化主义者的极端。
如何查看 HTML 文件？
我通常在本地浏览器中打开它（你可以让 Claude 打开它），或者上传到 S3 以获得可分享的链接。
生成 HTML 不是比 markdown 更慢吗？
确实更慢！HTML 可能需要 markdown 2-4 倍的时间，但我发现结果是值得的。
版本控制怎么办？
这确实是 HTML 最大的缺点之一。与 Markdown 相比，HTML 的 diff 噪音大且难以审查。
如何让 Claude 符合我的审美 / 不让它做得很难看？
frontend design 插件可以帮助 Claude 制作好看的 HTML 文件。但要匹配你自己公司的风格，你可以让 Claude 读取你的代码库，创建一个设计系统 HTML 文件。然后你可以将该设计系统文件作为其他 HTML 文件的参考。
保持参与感
以上所有内容想表达的是，我认为我使用 HTML 的真正原因是，我感觉与 Claude 的参与感更强了。我曾经开始担心，因为我不再深入阅读计划，我将不得不让 Claude 自行做决定。
但我很高兴地说，在使用 HTML 后，我比以往任何时候都更有参与感。希望你也能如此。