AsciiDoc 与 Markdown 对比

选择轻量级标记语言进行写作的最有说服力的理由是，尽量减少作者必须掌握才能立即投入生产的技术概念数量。换句话说，目标是能够*无摩擦地写作*。虽然这无疑是 AsciiDoc 和 Markdown 的共同目标，并且两者对于新手来说都非常容易上手，但本页将探讨为什么随着您的内容不断增长和演变，AsciiDoc 是 Markdown 的更佳替代方案。

从 Markdown 开始

最普遍的轻量级标记语言是 Markdown。（至少，一开始您是这么称呼它的）。Markdown 的主要优势在于其朴素的语法：其手册和备忘单是同一个东西。但这个优势也是它最大的弱点。

一旦作者需要比基本散文更复杂的东西（例如，表格、交叉引用、脚注、嵌入式 YouTube 视频等），他们就会发现自己不得不诉诸嵌入 HTML 或寻找功能更丰富的实现。Markdown 已成为不同实现（称为“方言”）的迷宫，这使得通用定义难以捉摸。

IETF 已声明“不存在‘无效’Markdown 之说”。请参阅这是 Markdown！或：标记及其不满。

故事的结局总是这样。您从 Markdown 开始。然后是 Markdown + X。然后是 Markdown + X + Y。您就这样一步步陷入了兔子洞。更糟糕的是，X 和 Y 经常需要您嵌入 HTML，不必要地将内容与呈现方式耦合，并破坏了可移植性。您选择 Markdown 的直觉是好的。只是有更好的选择。

进阶到 AsciiDoc

AsciiDoc 提供了一个更可靠的替代方案。AsciiDoc 语法比 Markdown 更简洁（或者至少与 Markdown 一样简洁）。同时，AsciiDoc 提供了强大的功能和灵活性，而无需使用 HTML 或“方言”来实现表格、描述列表、提示（提示、注意事项、警告等）和目录等基本语法。

重要的是要理解，AsciiDoc 最初是作为 DocBook XML 模式的纯文本替代品而设计的。AsciiDoc 不会像 Markdown 那样陷入“打地鼠”的游戏来满足出版需求。相反，AsciiDoc 语法在设计时就明确考虑了打印和 Web 的出版需求。如果需要，您可以使用 Asciidoctor 的 DocBook 转换器，充分利用 DocBook 工作流程中提供的海量工具。这就是为什么映射到 DocBook 等企业文档格式仍然是 AsciiDoc 的关键用例。

然而，AsciiDoc 的简单性足以使其成为 Markdown 的更好方言。但真正使 AsciiDoc 成为明智投资的是，其语法被设计为作为一项核心功能进行扩展。这种可扩展性不仅意味着 AsciiDoc 还有更多内容可供提供，并且有增长的空间，而且它还实现了确保您的内容最大化可重用的目标。

举例对比

下表显示了 AsciiDoc 语法与 Markdown 的对比。由于 AsciiDoc 支持比 Markdown 更广泛的语法，因此本次并排比较主要集中在语法重叠的区域。

AsciiDoc 语言特性与 Markdown 对比选集
语言特性	Markdown	AsciiDoc
粗体（受限）	`bold`	`bold`
粗体（无限制）	`bold`	`bold`
斜体（受限）	`italic`	`_italic_`
斜体（无限制）	不适用	`__i__talic`
等宽字体（受限）	`monospace`	`monospace`
等宽字体（无限制）	`m`onospace	``m``onospace
字面等宽字体	`https://:8080` `/issue/{id}`	`+https://:8080+` `+/issue/{id}+`
带标签的链接	`[Asciidoctor](https://asciidoctor.org.cn)`	`https://asciidoctor.org.cn[Asciidoctor]`
相对链接	`[user guide](user-guide.html)`	`link:user-guide.html[user guide] xref:user-guide.adoc[user guide]`
文件链接	`[get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/mydoc.pdf)`	`link:{site-url}/assets/mydoc.pdf[get the PDF]`
交叉引用	`See [Usage](#_usage). <h2 id="_usage">Usage</h2>`	`See <<_usage>>. == Usage`
块 ID（又称锚点）	`<h2 id="usage">Usage</h2>`	`[#usage] == Usage`
内嵌锚点	不适用	`. [[step-1]]Download the software`
带 alt 文本的内嵌图像	`![Logo](/images/logo.png)`	`image:logo.png[Logo]`
带 alt 文本的块状图像	不适用	`image::logo.png[Logo]`
章节标题*	`## Heading 2`	`== Heading 2`
引用块*	`> Quoted text. > > Another paragraph in quote.`	`____ Quoted text. Another paragraph in quote. ____`
字面块	`$ gem install asciidoctor`	示例 1. 缩进（一个或多个空格） `$ gem install asciidoctor` 示例 2. 分隔符 `.... $ gem install asciidoctor ....`
代码块*	```java public class Person { private String name; public Person(String name) { this.name = name; } } ```	`[source,java] ---- public class Person { private String name; public Person(String name) { this.name = name; } } ----`
无序列表	`* apples * orange * temple * navel * bananas`	`* apples * oranges temple navel * bananas`
有序列表	`1. first 2. second 3. third`	`. first . second . third`
主题分隔符（又称水平规则）*	`*** * * * --- - - - ___ _ _ _`	`'''`
排版引号（又称“智能引号”）	通过扩展开关启用，但对其应用方式的控制很少。	The `'90s popularized a new form of music known as "`grunge`" rock. It'll turn out to have an impact that extended well beyond music.
文档头	示例 3. 作为“前端内容”附加 `--- layout: docs title: Writing posts prev_section: defining-frontmatter next_section: creating-pages permalink: /docs/writing-posts/ ---`	示例 4. 原生支持！ `= Writing posts :page-layout: base :showtitle: :prev_section: defining-frontmatter :next_section: creating-pages`
警告框	不适用	TIP: You can add line numbers to source listings by adding the word `numbered` in the attribute list after the language name.
边栏	不适用	`.Lightweight Markup ** Writing languages that let you type less and express more. **`
块标题	不适用	`.Grocery list * Milk * Eggs * Bread`
包含	不适用	`include::intro.adoc[]`
URI 引用	`Go to the [home page][home]. [home]: https://example.org`	`:home: https://example.org Go to the {home}[home page].`
自定义 CSS 类	不适用	`[.path]_Gemfile_`

* Asciidoctor 也支持 Markdown 的该语言特性语法。

您可以看到，在几乎所有情况下，AsciiDoc 与 Markdown 相比使用的标记字符数相同或更少

AsciiDoc 使用相同的标记字符数或更少，与 Markdown 相比，在几乎所有情况下都是如此。
AsciiDoc 使用一致的格式方案（即，它具有一致的模式）。
AsciiDoc 可以处理嵌套内嵌（和块状）格式的所有排列组合，而 Markdown 经常在此处失效。
AsciiDoc 处理 Markdown 不支持的情况，例如内词标记的正确方法、源代码块和块状图像。

某些 Markdown 方言，例如 Markdown Extra，支持表格和描述列表等附加功能。但是，由于这些功能未出现在“纯”Markdown 中，因此未包含在比较表中。但它们受到 AsciiDoc 的原生支持。

Asciidoctor（用于在 GitHub 和 GitLab 上转换 AsciiDoc）模拟了 Markdown 语法的一些常见部分，例如标题、引用块和分隔式代码块，从而简化了从 Markdown 到 AsciiDoc 的迁移。有关详细信息，请参阅 Markdown 兼容性。