跳到主要内容

Markdown 转 AsciiDoc 实战:把技术文档迁进更强的标记格式

讲清楚 AsciiDoc 比 Markdown 强在哪,标题为什么用等号、链接为什么倒着写,以及怎样把现有 Markdown 文档批量迁进 Asciidoctor 和 Antora 工具链而不用手动重打。

发布于 作者 李雷
#AsciiDoc #Markdown #技术文档 #文档工具链

Markdown 转 AsciiDoc 实战:把技术文档迁进更强的标记格式

写了几年 Markdown,你大概也撞过这堵墙:文档一长,Markdown 就不够用了。没有原生的告示框,没有 include 把多个文件拼起来,没有交叉引用,也没有属性变量。等到要做一本几百页的手册或一个多版本文档站,这些缺口就会变成每天都要绕的弯路。AsciiDoc 正是为补这些缺口而生的格式,而把存量的 Markdown 搬过去,是绕不开的第一步。

AsciiDoc 是什么,凭什么比 Markdown 强

AsciiDoc 是一种纯文本标记,由 Asciidoctor 这套渲染引擎读取,Antora 文档站和大量技术书流水线都用它,O'Reilly 的不少书就直接从 .adoc 出版。它长得和 Markdown 很像,上手几乎没有门槛,但功能多出一大截:告示框(NOTE、WARNING 这类带样式的提示块)、include 指令把一份长文档拆成多个文件再拼回去、属性变量统一管理版本号和产品名、交叉引用让章节之间能互相跳转。这些都是长文档和书籍真正需要的东西,而 Markdown 标准里一个都没有。

简单说:Markdown 适合 README 和聊天,AsciiDoc 适合手册和书。当你的内容从「一页」长成「一本」,迁移到 AsciiDoc 就不是折腾,而是省事。

语法差异:从井号到等号

最直观的差别在标题。Markdown 用井号的数量标级别,AsciiDoc 用等号的数量,正好镜像。具体对应是这样的:

  • Markdown #(H1)转成单个 =,这是 AsciiDoc 的文档标题级
  • ## 转成 ==
  • ### 转成 ===
  • 一直到 ###### 对应 ======(h6)

等号的数量必须对上目标级别,差一个,Asciidoctor 就会把章节嵌套错位。这个差一位的坑,正是手动迁移最容易出错的地方。

一个真实的转换例子

拿一段最常见的 Markdown 片段看转换结果。输入:

# 安装指南
请运行下面的命令:
[官方仓库](https://example.com/repo)

转成 AsciiDoc 后:

= 安装指南
请运行下面的命令:
https://example.com/repo[官方仓库]

注意两处变化:标题的 # 变成了单个 =;链接顺序整个反了过来,AsciiDoc 把网址放前面、标签放进后面的方括号,写成 url[text],和 Markdown 的 [text](url) 刚好相反。围栏代码块也类似,Markdown 的三反引号加语言名会变成 [source,lang] 属性行加上 ---- 围起来的 listing 块。这些规则一条条手敲都对不容易,机器替你做才靠谱。

我自己迁移文档的体会

我去年把一个项目的运维手册从 Markdown 编辑器迁进团队的 AsciiDoc 仓库,一开始想着手动改,结果光是标题层级和链接顺序就来回返工了三遍,Asciidoctor 编译总有几节嵌套错位。后来改成先用工具整段转,再针对告示框和 include 这类 AsciiDoc 独有的部分手工补,效率立刻翻倍。结论很朴素:机械的语法替换交给工具,人只管 AsciiDoc 比 Markdown 多出来的那部分结构。

怎样把文档迁进 AsciiDoc 工具链

迁移路径其实不复杂,关键是分清哪些能自动、哪些要手补:

  1. 用 Markdown 转 AsciiDoc 转换器 把每个 .md 文件整段转成 .adoc,标题、代码块、链接、图片宏一次到位。
  2. 把转好的 .adoc 放进 Asciidoctor 或 Antora 的目录结构,跑一次本地编译,看哪些节点没渲染对。
  3. 补上 AsciiDoc 独有的部分:用 include 把长文档拆开,用属性变量收口版本号,需要提醒的地方加告示框。
  4. 反过来也常用:如果团队最终决定回到 Markdown,或者要在网页上预览,可以用 Markdown 转 HTML 工具 先把内容渲染出来对照。

整个过程里,转换工具承担的是最枯燥也最容易出错的语法搬运,把井号、链接、围栏一次性换好,你省下的时间就能花在文档结构本身上。

Made by Toolora · Updated 2026-06-13