为什么我让 AI 输出 HTML，不输出 Markdown

一次把学习笔记做成博客上电子书的实战记录

这个月到现在,我没单独发过一篇新博文——但我做了别的事，发布了一本“电子书”。

确切地说，是一本基于我软考系统架构设计师备考笔记整理出来的电子书，一共 24 章，放在博客的「书架」页面上。

写这篇文章不是为了讲怎么做一本书。做书本身并不复杂，真正值得记下来的，是做的过程里我得到的一个判断：

让 AI 输出 HTML，比让它输出 Markdown 更好。

起因：被反复精炼的笔记

最近一个月，我在冲刺复习软考系统架构设计师。

主要跟着《系统架构设计师 32 小时通关》这本书在学。它已经是一个非常精炼的版本了，把整个考纲压缩到一本不算厚的教材里。我做笔记的目标，是在这个基础上再次精炼——一章一章读完，把核心概念、易混点、必考点抽出来重新写一遍。两个目的：一个是在写的过程中加深记忆，一个是后面随时可以拿出来快速复习。

笔记用的是语雀的 markdown，一章一章写下去，到 5 月底差不多写满了 24 章。

写完之后，自然就想：既然写都写了，索性把它放到博客上。一是自己复习时随时能看，不依赖语雀客户端；二是顺手成为博客的内容资产，留在那儿。

笔记的最终归宿不应该是文档库里没人点开的页面。

这就引出了一个问题：用什么格式发布到博客上？

把笔记发布到博客之前，我面对一个看似细节、其实决定阅读体验的选择——让 AI 把笔记从 markdown 重新组织一遍由博客渲染，还是直接让 AI 输出完整的 HTML 嵌进去？

最后我选了后者。理由有三个，每一个都不是"哪个更好用一点"的细枝末节，而是格式本身的能力边界。

Markdown 的语法表达力其实非常窄。井号、星号、列表、表格——就这些。如果你需要 callout 卡片、双栏布局、彩色高亮、内嵌 SVG、对比卡片、知识地图，markdown 全部做不到，或者得靠扩展语法去 hack。

而 HTML 一开始就把这些工具全部给你。学习笔记里需要的概念卡片、易错点高亮、章节小结，用 HTML 自然得很。

Markdown 能表达结构，不能表达设计。

Markdown 是中间格式，最终要靠渲染器才能变成读者看到的东西。同一篇 markdown 在 GitHub、Notion、语雀、Hexo、Next.js 自带的渲染器里，长得都不一样。一旦换工具或者改版式，整套笔记都得重新调整。

HTML 不一样。HTML 一旦写出来，在浏览器里就是最终态——所见即所得，不再受任何渲染器摆布。

这一条是我觉得最关键的。

当你让 AI 输出 markdown，AI 在做的事情是「打标记」——标记这一段是标题、那一段是列表、再下一段是引用。版式是延后决定的，由渲染器来处理。

当你让 AI 输出 HTML，AI 在做的事情完全不一样——它在「做设计」。它会决定这一段用什么布局、要不要加底色、是不是用卡片、关键句要不要单独提出来。设计权交还给了 AI 自己。

这两种工作模式产出来的东西，根本不是一回事。

实操比想象的简单。

整个流程就两步：

第一步是转格式。把语雀里的某一章笔记复制出来，喂给 AI，让它按统一的样式约定输出完整的 HTML。我没有写批处理脚本，就是一章一章手动来——24 章，一会就能搞完。

第二步是接进博客。这里有一个我没预料到的坑：博客是用 Next.js 搭的，有自己的全局样式和布局。如果直接把 AI 输出的 HTML 嵌进博客页面，AI 设计的样式会和博客本身的 CSS 互相打架——颜色被覆盖、字号被重置、卡片背景消失。

最后采用的方案是 iframe。给每一章开一个独立的子页面，HTML 完整渲染在 iframe 里，博客主页面只负责导航和容器。两边的 CSS 完全隔离，互不干扰。

最后加一个「书架」页面，把 24 章按顺序聚合，加一个简单的章节目录。逻辑非常简单，没什么高深的工程。

做完这一本之后我意识到，HTML 这个格式不只适合学习笔记。

它特别适合需要"看"的内容——产品展示、教学讲义、操作手册、技术说明。这些内容的核心价值不在文字本身，而在文字、配图、版式一起呈现出来的样子。HTML 把这种整体性一次性交付给读者。

而当你手上积累了一批同主题的 HTML 文档时，自然的下一步就是把它们整理成合集——一本书、一份手册、一套教材。这件事不需要复杂的工具，一个简单的聚合页加章节目录就够了。

后续我也会把一些经典书籍通过 AI 进行拆解，然后制作 html 放到书架里。

这本《软考系统架构设计师》笔记电子书已经放在博客的书架上了。