技术文档还在全靠 Markdown？它可能真的在拖你后腿

大家好，这里是架构资源栈！点击上方关注，添加“星标”，一起学习大厂前沿架构！

关注、发送C1即可获取JetBrains全家桶激活工具和码！

Markdown 这玩意儿，谁不用？
写 README、记笔记、写博客，全靠它，简单、直观、上手快。很多团队甚至把“全站 Markdown”当成技术文档基础设施的一部分。

但一旦文档规模上来，涉及多终端发布、结构化检索、AI Agent 消费、跨系统复用这些需求时，Markdown 的短板会被放大得非常难看——它更像是“最低公分母”，而不是可靠的“文档真相源（source of truth）”。

这篇就来聊聊：

  • 为什么说 Markdown = 内容世界里的“隐式类型系统”
  • 什么时候它会把你拖进坑里
  • 几个更适合严肃技术文档的备选方案

一、Markdown 最大的问题：它几乎不描述“是什么”

Markdown 的优点大家都知道：

  • 纯文本、可读性好
  • 写起来快，开发者友好
  • 在 GitHub、静态站、编辑器里到处都能用

但它有一个致命缺点：几乎不带“语义”。

对机器来说，一段 Markdown 大概长这样：

  • #：大概是个标题
  • - / *：大概是个列表
  •

但它不知道：

  • 这个标题是“概念解释”还是“操作步骤标题”
  • 这个列表里的每一项是“步骤（step）”、还是“注意事项（note）”、还是“纯罗列”
  • 这段代码是“命令行指令”、“配置片段”还是“完整示例”

对人类眼睛来说都差不多；
对搜索引擎、IDE 插件、AI Agent 来说，差别就很大了。

更现实一点的场景：

  • 你想把一份内容同时导出为：HTML / PDF / ePub / man page
  • 你想让 LLM 根据文档自动生成“操作步骤”、“API 参数说明”、“环境要求”

如果文档只有 Markdown 这点结构信息，机器只能靠猜，没有任何“结构保证”。

image

二、把 Markdown 想象成“隐式类型系统”

可以借用一下程序语言的比喻：

  • JavaScript、Python 这类是“隐式类型”

    • 写起来灵活
    • 但编译器给不了多少保证

  • TypeScript、Rust 则是“显式类型、强约束”

    • 写的时候麻烦一点
    • 但能在编译期抓出一堆问题，整体工程更稳

Markdown 就是文档世界里的 “隐式类型”：

  • 怎么写都行，没有 schema，没有校验
  • 同一层级的标题，在 A 文档里表示“概念解释”，在 B 文档里表示“操作手册”
  • 机器完全不知道它们“语义上是不是同一类东西”

而且还不止一种 Markdown，常见几种：

你以为自己在写“Markdown”，
实际上是在写“某个实现的 Markdown 方言”，
换个渲染器就可能各种小问题：

  • 有的支持脚注，有的直接无视
  • 有的对软换行有特别规则
  • 代码块语法也可能不兼容

结果就是：非常适合写一篇文章，极不适合作为长期演进的大型文档体系基础。

三、MDX：大家都在 Markdown 上“偷偷造轮子”

当团队发现 Markdown 表达力不够的时候，常见的补救手段是：MDX。

比如这样的写法：

# Install

<Command>npm install my-library</Command>

<Command> 根本不是 Markdown，它是个 React 组件：

  • 在这个网站上，渲染成统一风格的“命令块”
  • 对编辑者来说，这样比 ```bash 看的更语义化

问题是：

  • 这套东西 只在这一家站点里有意义
  • 你想把这段文档同步到别的系统上，对方也得实现一模一样的 <Command> 组件
  • 即使对方也支持，渲染细节也未必一致

换句话说，大家本能地觉得“只靠 Markdown 不够用”，
于是开始在上面“造私有的语义层”，
结果是：结构变强了，但可移植性直接归零。

四、为什么要认真对待“语义标记（semantic markup）”

语义标记关心的是：内容是什么，而不仅仅是“长什么样”。

比如同样是一行内容，对机器来说这几种差别很大：

  • <li>：普通列表项
  • <step>：操作步骤
  • <note>：提示或备注
  • <warning>：高危提示

这对几个方面都很关键。

1. 内容复用 & 多渠道发布

如果源文档带语义：

  • 可以按需转换为 HTML / PDF / ePub / man page / Markdown 等

  • 在转换过程中，可以根据类型定制展示：

    • <command> → 统一风格的命令行块
    • <step> → 自动编号、折叠
    • <warning> → 高亮红框

如果源头只有 Markdown：

  • 解析出来最多只有“标题 + 列表 + 段落 + 代码块”

  • 想在后处理中重新识别“哪些是步骤、哪些是概念”

    • 只能靠语义模型 / 正则去猜
    • 准确率和可维护性都很糟糕

一句话：结构信息只能从源头写入，很难在下游魔法补回去。

2. 机器消费：LLM / Agent / IDE 集成

对 AI 而言：

  • <step> = 100% 确定的“操作步骤”
  • 列表里的 - xxx = “可能是步骤、也可能是吐槽”

前者可以直接用来生成交互式向导、脚本、校验器；
后者只能当普通文本读。

早年的 XML Web Service 之所以流行，很大程度上也是这个理由：
结构 + schema 可以给机器足够多的“确定性信息”。
今天 JSON 一样要配合 JSON Schema 来用，道理相同。

五、几种比 Markdown 更“长远”的文档格式

接下来看看几种常在技术文档体系里出现的选手：表达力和结构都比 Markdown 强很多。

1. reStructuredText：Python 社区的老牌选手

reStructuredText（reST）是 Python / Sphinx 生态的标记语言，
语法是纯文本，但支持丰富的“指令（directive）”和“角色（role）”。

示例：

Installation
============

.. code-block:: bash

   npm install my-library

.. note::  
   This library requires Node.JS ≥ 22.

See also :ref:`usage-guide`.

这里可以看到：

  • .. code-block:: bash：明确是代码块，语言是 bash
  • .. note::：语义上的“注释/说明”
  • :ref:：显式的交叉引用

reST 还有 figure、sidebar、citation 等一堆结构化元素，
都可以在渲染时被“定制化对待”。

2. AsciiDoc：更易读的人类友好型语义标记

AsciiDoc 也是纯文本语法，但设计时就考虑到了“结构 + 参数化 + 多渠道输出”。

示例：

= Installation
:revnumber: 1.2
:platform: linux
:prev_section: introduction
:next_section: create-project

[source,bash]
----
npm install my-library
----

NOTE: This library requires Node.JS ≥ 22.

See <<usage,Usage Guide>> for examples.

里面有几个关键点：

  • 顶部的 :revnumber:、:platform: 等是文档属性

    • 方便做版本、平台过滤、条件内容

  • [source,bash] + ---- 明确说明“这是 bash 源码块”

  • NOTE: 是标准的“提示”语义

  • <<usage,Usage Guide>> 是交叉引用

借助 Asciidoctor 工具链：

  • 可以从 AsciiDoc 输出 HTML / PDF / ePub / DocBook 等
  • 也可以把现有 Markdown 迁移过来（有成熟的迁移文档和工具）

迁移指南可看：
https://docs.asciidoctor.org/asciidoctor/latest/migrate/markdown

3. DocBook：偏“工业级出版”的 XML 模型

DocBook 是专门为技术出版设计的 XML 模型。

示例：

<article id="install-library">
  <title>Installation</title>
  <command>npm install my-library</command>
  <note>This library requires Node.JS >= 22</note>
  <xref linkend="usage-chapter">Usage Guide</xref>
</article>

每个标签都有清晰语义：

  • <command>：命令
  • <note>：注释/说明
  • <xref>：交叉引用

DocBook 还内置了大量领域标签：

  • 函数名、变量名、应用名、菜单、快捷键、UI 元素等
  • 支持索引项、术语表，方便自动生成索引和术语解释

借助已有的 XSLT 样式：
https://docbook.org/tools

可以稳定输出 HTML / PDF / man page，甚至再导出为 Markdown。

代价当然是：XML 比 Markdown 啰嗦得多。

4. DITA：企业级结构化内容的终点站

DITA（Darwin Information Typing Architecture）是企业里常见的结构化内容标准，基于 XML，主打：

  • 主题化写作（topic-based）
  • 内容重用（conref、条件过滤）
  • 多产品、多版本、多渠道发布

示例：

<task id="install">
  <title>Installation</title>
  <steps>
    <step><cmd>npm install my-library</cmd></step>
  </steps>
  <prolog>
    <note>This library requires Node.js >= 22</note>
  </prolog>
</task>

语义非常明确：

  • <task>：一个任务
  • <steps> / <step>：任务步骤
  • <cmd>：执行命令

再配合过滤和重用，可以在一份内容源基础上，输出：

  • 不同产品线的定制版本
  • 不同平台（Linux / Windows）的变体
  • 不同渠道（Web / PDF / 帮助文档）的呈现

六、别急着嫌 XML：你可能已经在“间接付出成本”了

很多开发者看到 XML 就本能抵触：

“又长又难写、工具又少，团队肯定不买账。”

但如果你团队已经在：

  • 用 MDX 自己造组件语义
  • 用各种插件给 Markdown 打补丁
  • 写一堆脚本在构建时“猜结构”、“改 AST”

那说明你已经在为“语义 + 结构”付费用了，只是：

  • 付的是隐形复杂度
  • 得到的是非标准、不可移植的私有解决方案

相比之下，选一个成熟标准（reST / AsciiDoc / DocBook / DITA）：

  • 工具链、最佳实践、生态都比较成熟
  • 学习成本是一次性的
  • 长期来看更容易维护、扩展、迁移

七、怎么选？给不同规模的项目一个简单建议

可以按“文档复杂度”来划分：

  1. 小体量 / 短生命周期文档

    • 例如 README、内部一次性说明、Demo 说明
    • → 用 Markdown 就好，简单高效

  2. 中等规模的开发者文档站点

    • 需要结构化、交叉引用、少量复用

    • → 优先考虑 reStructuredText 或 AsciiDoc

      • 编辑体验接近 Markdown
      • 结构比 Markdown 强多了

  3. 大型、长期演进的文档体系

    • 多产品、多版本、多渠道发布
    • 有专职技术文档团队
    • → 考虑 DocBook / DITA 这类 XML 方案

无论选哪个，有一个共识比较重要：

源头尽量用“信息最丰富”的格式，往下可以裁剪成 Markdown，但别反过来。

Markdown 非常适合作为“开发者友好的输出格式”，
但不一定适合作为你整个文档体系的“唯一真相源”。

八、稍微动手试试会更有感觉

如果想从“停留在 Markdown”往前挪一点，可以这样练手：

当你真实感受到：

  • “同一份源文档”可以就这么往多个渠道、多个格式输出
  • AI / Agent 可以准确识别“步骤 / 命令 / 注意 / 概念”

你就很难再把 Markdown 当作“万用解决方案”了。它依然好用，只是该让位的地方，得学会让位。

喜欢就奖励一个“👍”和“在看”呗~

image

posted @ 2025-12-14 00:43  StriverD  阅读(1)  评论(0)    收藏  举报