选择轻量级标记语言进行写作最引人注目的理由是为了最小化作者为了立刻高效工作必须掌握的技术概念数量。换句话说，目标是能够_无障碍写作_。虽然这确实是AsciiDoc和Markdown两者的目标，它们对于新来者都非常容易上手，但本页面探讨了为何AsciiDoc是一个更适合你的内容随着成长和演变而选择的Markdown的替代方案。

从Markdown开始

目前最流行的轻量级标记语言是Markdown。（至少，最初你称它为Markdown。）Markdown的主要优点在于它的原始语法：它的手册和备忘单是一回事。但是，这一优势也是它最大的弱点。

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

Note
 IETF宣布“‘无效’的Markdown是不存在的。”详情参见https://tools.ietf.org/html/rfc7763#section-1.1[这就是Markdown！或者说：标记及其不满情绪^]。

故事总是这样不可避免地发展。你从Markdown开始。然后是Markdown加上X。然后是Markdown加上X和Y。你就这样一头扎进了兔子洞。更糟糕的是，X和Y通常还要求你掺入HTML，不必要地将内容与表现形式结合在一起，破坏了可移植性。你选择Markdown的本能是对的。只是有更好的选择而已。

毕业到AsciiDoc

AsciiDoc提供了一个更为合理的选择。AsciiDoc的语法比Markdown要简洁（或者至少和Markdown一样简洁）。同时，AsciiDoc在不需要使用HTML或“变种”来实现诸如表格、描述列表、警示（提示、注解、警告等）和目录等基本语法的情况下，提供了强大和灵活性。

要了解AsciiDoc最初被设计为DocBook XML模式的纯文本替代品是很重要的。AsciiDoc不像Markdown那样陷于解决出版需求的打地鼠游戏。相反，AsciiDoc的语法是明确地考虑到出版的需求而设计的，无论是印刷还是网络。如果需要，你可以使用Asciidoctor的DocBook转换器，充分利用DocBook工作流程可用的大量工具。这也是为什么将AsciiDoc映射到像DocBook这样的企业文档格式仍然是AsciiDoc的一个关键用例。

尽管如此，AsciiDoc由于其简单性足以作为Markdown的更好选择。但是，真正让AsciiDoc值得投资的是，其语法设计为核心功能之一便于扩展。这种可扩展性不仅意味着AsciiDoc能提供更多的功能，并且有增长的空间，它也实现了确保您的内容能够最大限度复用的目标。

通过例子比较

下表展示了AsciiDoc语法与Markdown语法的比较。由于AsciiDoc支持比Markdown更广泛的语法范围，这一并排对比主要聚焦于两者语法重叠的部分。

Table 1. AsciiDoc 语言特性与 Markdown 的比较选集
语言特性 Markdown AsciiDoc

加粗（受限）

 
**粗体**
 
**加粗**
------

加粗（不受约束）a
[source, markdown]

粗体















**粗体**






斜体（受限的）a


[source, markdown]
----
斜体
----










_斜体_






斜体（不受约束的）


n/a










斜体






Monospace (constrained)






monospace`














monospace`








Monospace (unconstrained) a








monospace










m``onospace






固定间距










http://localhost:8080`
`/issue/{id}`










+http://localhost:8080+`
`+/issue/{id}+`








带标签a的链接








[Asciidoctor](https://asciidoctor.org)










https://asciidoctor.org[Asciidoctor]








相对链接a








[user guide](user-guide.html)














link:user-guide.html[user guide]
xref:user-guide.adoc[user guide]






文件链接a


[source, markdown]
----
[获取PDF]({% raw %}{{ site.url }}{% endraw %}/assets/mydoc.pdf)
----










link:{site-url}/assets/mydoc.pdf[get the PDF]








交叉引用a








See [Usage](#_usage).

<h2 id="_usage">Usage</h2>










参见<<_使用方法>>。

== 使用说明








块标识符（又称锚点）a








<h2 id="usage">Usage</h2>










[#usage]
== 使用说明








内联锚点








n/a






. [[step-1]]下载软件
  ----

带有替代文本a的内联图像
[source, markdown]








![Logo](/images/logo.png)


















image:logo.png[Logo]










带有替代文字的图像块


n/a






image::logo.png["标志"]










Section heading*






## Heading 2










== 二级标题










Blockquote*






> 引用的文本。 >
> 引用中的另一段话。
  ----










____
引用的文本。

引用中的另一个段落。
____










Literal block






$ gem install asciidoctor








缩进（由1个或多个空格）




$ gem install asciidoctor








分隔的




....
$ gem install asciidoctor
....










Code block*






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;
  }
}
----
....










无序列表






* 苹果
* 橘子/橙色
  * 庙宇
  * 肚脐
香蕉
--










* 苹果
* 橙子
** 庙宇
** 肚脐
香蕉
--
有序列表a
[source, markdown]








    

  1. 

    首先
    

    2. 

  2. 

    秒
第三
    

    3. 






















. 首先
. 秒
第三
--

主题分割线（又名水平线）* a
[source, markdown]










星星














下划线`_ _ _`在这里似乎没有提供任何可以翻译的内容。如果您希望翻译特定的文本，请提供具体的句子或单词。






















'''''''''
---------

排版引号（又称“智能引号”）






通过一个扩展开关启用，但是对它们的应用提供很少的控制。a






[source]
----
20世纪90年代流行起一种被称为“垃圾摇滚”的新形式音乐。
它最终产生的影响远远超出了音乐本身。
----


文档头部a，被当作“前言”强加上去
[source, markdown]
----
---
layout: docs
title: 写作帖子
prev_section: 定义前言
next_section: 创建页面
permalink: /docs/writing-posts/
---
----
原生支持！
[source]
----
= 撰写帖子
:page-layout: base
:showtitle:
:prev_section: defining-frontmatter
:next_section: creating-pages
----


警告


n/a










TIP: 你可以通过在语言名称后的属性列表中添加单词`numbered`来为源代码列表添加行号。








侧边栏




n/a






.轻量级标记语言
****
编写让你少打字、表达更多的语言。
****








条块标题








n/a






.杂货清单
* 牛奶
* 鸡蛋
面包
--

包括






非适用










include::intro.adoc[]






URI参考a


[source, markdown]
----
前往[主页][home]。


[home]: https://example.org
----










:home: https://example.org

前往{home}[主页]。






Custom CSS classes


n/a









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






你可以看到AsciiDoc相比于Markdown有以下优势：
* AsciiDoc在几乎所有情况下与Markdown相比，使用相同或更少的标记字符数。
* AsciiDoc 使用一种一致的格式化方案（即，它有一致的模式）。
* AsciiDoc可以处理所有嵌套的内联（和块级）格式的排列组合，而Markdown经常处理不好。
* AsciiDoc处理了Markdown无法处理的情况，比如内部单词标记的正确方法、源代码块和块级图片。






注意：某些Markdown变体，比如Markdown Extra，支持额外的特性，如表格和描述列表。
  然而，由于这些特性在“纯粹”的Markdown中并不出现，它们没有被包含在比较表中。
  但是，这些特性被AsciiDoc原生支持。






Asciidoctor，它被用于在GitHub和GitLab上转换AsciiDoc，模拟了Markdown语法的一些常见部分，比如标题、块引用和围栏代码块，从而简化了从Markdown到AsciiDoc的迁移。
  具体详情，请参见Markdown 兼容性。