Skip to content

2026-07-03-markdown's-big-brother-say-hello-to-asciidoc.md

Latest commit

 

History

History
28 lines (21 loc) · 3.15 KB

2026-07-03-markdown's-big-brother-say-hello-to-asciidoc.md

File metadata and controls

28 lines (21 loc) · 3.15 KB
Raw

Markdown's Big Brother: Say Hello to AsciiDoc

TL;DR

文章介绍AsciiDoc标记语言，它比Markdown更强，原生支持表格、条件输出等高级功能，支持模块化与变量重用。结合adoc Studio和Git，可高效协作、一键导出多格式，实现文档即代码。

Summary

这篇文章介绍了 AsciiDoc 标记语言，把它定义为 Markdown 的“大哥”，即一种更强大、更适合复杂文档的替代方案。它重点阐述了 AsciiDoc 的核心特性，以及在与版本控制结合时的优势。

文章首先承认 Markdown 的流行和简便，但指出当文档规模变大或需要表格、脚注、交叉引用等高级功能时，Markdown 往往要依赖第三方扩展，这会带来兼容性问题。而 AsciiDoc 从设计之初就内置了这些能力，拥有统一的生态，不会像 Markdown 那样出现各种方言混杂的情况。

接着，文章用具体示例展示了 AsciiDoc 的写作风格：

  • 文档元数据直接写在文件头部，用 = 开头定义标题、作者、日期，无需额外的 YAML 配置文件。
  • 标题层级用等号数量表示，比如 == 是二级标题，这让文档结构在原始文本中也非常直观。
  • 文本格式（粗体、斜体、等宽）与 Markdown 近乎一致，学习成本低。
  • 列表支持无序和有序，有序列表在调整顺序时会自动重新编号，避免了手动修改的麻烦。
  • 表格使用简洁的网格语法，每行独立，在 Git 中查看差异时清晰可辨，解决了 Markdown 多行表格难以比对的痛点。
  • 属性相当于可重用变量，只需定义一次，就能在整个文档中统一更新版本号、网站 URL 等重复内容。
  • 模块化通过 include 指令将大型文档拆分成多个文件，再动态组合，便于团队协作和内容复用。
  • 条件内容可根据定义的属性（如 beginner、advanced）选择性地输出不同内容，实现从单一主文档生成多份定制化文档，比如同时制作入门指南和高级教程。

关于导出，文章提到了传统的命令行方式，但更推荐使用免费的编辑器 adoc Studio。这个工具把编写、样式管理、导出整合在一起，支持一键生成 HTML、PDF 等多种格式，而且用一套 CSS 就能同时控制网页和打印的样式，无需接触终端，还可在 Mac、iPad 和 iPhone 上跨设备使用。

此外，文章强调了“文档即代码”的理念。将 AsciiDoc 文件保存在 Git 仓库中，可以像管理代码一样管理文档：通过 Pull Request 协作、分支隔离未来版本的文档、完整追溯修改历史。由于 AsciiDoc 是纯文本且单行对应单行内容，Git 的差异对比非常干净。配合 Tower 等 Git 客户端，能让整个流程更加流畅。

总体而言，这篇文章将 AsciiDoc 描绘成一种兼具轻量语法和强劲功能的标记语言，尤其适合需要长期维护、多版本输出、并依赖版本控制的文档项目，为那些被 Markdown 局限困扰的用户指出了一个新的选择方向。