AsciiDoc 作者指南

本指南将温和地介绍 AsciiDoc，这是一种*纯文本*文档*语法*和*处理器*。本介绍适用于任何想要减少编写和发布内容（无论是技术文档、文章、网页还是经典的散文）所需精力的人。

如果您想了解 AsciiDoc 的全部内容，请参阅关于 AsciiDoc。如果您正在寻找 AsciiDoc 语法的简洁概述，请查阅AsciiDoc 语法快速参考。

在本指南中，您将学到

  • AsciiDoc 文档的基本结构

  • 如何创建您的第一个 AsciiDoc 文档

  • 如何添加其他结构元素，如列表、块引用和源代码

  • 如何将 AsciiDoc 文档转换为 HTML、DocBook 和 PDF

除了涵盖 AsciiDoc 基础知识外，本指南还提供了一套约定，以帮助您创建更一致的文档并最大限度地提高您的写作效率。

让我们开始学习 AsciiDoc 吧！

用 AsciiDoc 写作

本节的目标是教您如何编写第一个 AsciiDoc 文档。希望回顾时，您会同意这很简单。

您在 AsciiDoc 上的冒险始于您喜欢的文本编辑器。

它只是文本，伙计。

由于 AsciiDoc 语法只是*纯文本*，您可以使用*任何*文本编辑器编写 AsciiDoc 文档。您不需要 Microsoft Word、OpenOffice Writer 或 Google Docs 等复杂的文字处理程序。事实上，您*不应该*使用这些程序，因为它们会向您的文档添加（您看不见的）冗余，并使转换变得繁琐。

虽然任何文本编辑器都可以，但我建议选择支持 AsciiDoc 语法高亮的编辑器。*颜色*为文本带来对比度，使其更易于阅读。高亮还会在您输入内联或块元素的正确语法时进行确认。

macOS 上最受欢迎的纯文本编辑应用程序是*TextMate*。Linux 上类似的工具是*GEdit*。在 Windows 上，请避开 Notepad 和 Wordpad，因为它们会生成不跨平台的纯文本。不如选择像*Notepad++*这样的通用文本编辑器。如果您是程序员（或内心有极客情结的作家），您可能会更喜欢*Vim*、*Emacs*或*Sublime Text*，这些都可以在跨平台使用。所有这些编辑器共有的关键特性是对 AsciiDoc 的语法高亮。

打开您喜欢的文本编辑器，准备好编写一些 AsciiDoc 内容吧！

内容为王！

文档中的大部分内容是段落文本。这就是为什么 Asciidoctor 不需要任何特殊的标记或属性来指定段落内容。您只需开始输入即可。

在 Asciidoctor 中，相邻或连续的文本行组成一个段落元素。要在另一个元素（例如章节标题或表格）之后开始新段落，请按两次RETURN键插入一个空行，然后继续输入您的内容。

AsciiDoc 文档中的两个段落
This journey begins one late Monday afternoon in Antwerp.
Our team desperately needs coffee, but none of us dare open the office door.

To leave means code dismemberment and certain death.
使用默认（html5）转换器和样式表（asciidoctor.css）渲染的两个段落

这个故事发生在一个周一晚上的安特卫普。我们的团队急需咖啡，但我们谁都不敢打开办公室的门。

离开意味着代码被肢解和死亡。

就这样，*您正在用 AsciiDoc 写作！*正如您所见，这就像写电子邮件一样。

将文件保存为扩展名为 .adoc。

如果您想了解如何将文档转换为 HTML、DocBook 或 PDF，请跳至转换文档部分。

换行文本和硬换行

由于 Asciidoctor 在转换文档时会将相邻的文本行合并到同一个段落中，这意味着您可以换行段落文本，或者将每个句子或短语放在单独的行上。换行符不会出现在输出中。

但是，如果您希望在段落中保留换行符，可以使用空格后跟加号（+）或为该段落设置 hardbreaks 选项。这将导致每个行后出现一个可见的换行符（例如 <br>）。

使用空格后跟加号（+）保留换行符
Rubies are red, +
Topazes are blue.

红宝石是红色的，
黄玉是蓝色的。

使用 hardbreaks 选项保留换行符
[%hardbreaks]
Ruby is red.
Java is black.

红宝石是红色的。
Java 是黑色的。

要保留整个文档中的换行符，请将 hardbreaks 属性添加到文档的标题中。

使用 hardbreaks 属性在整个文档中保留换行符
= Line Break Doc Title
:hardbreaks:

Rubies are red,
Topazes are blue.

广告

有些陈述您可能希望引起注意，方法是将它们从内容流中移除并加上优先级标签。这些称为广告。它们的渲染样式由分配的标签（即值）决定。Asciidoctor 提供五种广告样式标签

  • 注意

  • 提示

  • 重要

  • 警告

  • 警告

谨慎与警告

在选择广告类型时，您可能会在“谨慎”和“警告”之间感到困惑，因为这两个词经常互换使用。这里有一个简单的规则可以帮助您区分两者

  • 使用*警告*来建议读者*谨慎行事*（即，小心）。

  • 使用*警告*来告知读者存在的危险、伤害或后果。

要获得更深入的分析，请参阅https://www.differencebetween.com/difference-between-caution-and-vs-warning/。

当您想引起对单个段落的注意时，请在段落的第一行以您想使用的标签开头。标签必须大写，后跟冒号（:）。

广告段落语法
WARNING: Wolpertingers are known to nest in server racks.  (1) (2)
Enter at your own risk.
1 标签必须大写，后跟冒号（:）。
2 段落的第一行与标签之间用一个空格隔开。
结果：广告段落
狼人以在服务器机架中筑巢而闻名。请自行承担风险。

广告段落会在装订处显示广告标签——或其对应的图标——在一个呼叫框中。通过在文档中设置 icons 属性来启用图标。

广告还可以包含任何块内容，我们稍后将介绍。

轻微标点，强烈影响

就像我们在说话时强调某些词语和短语一样，我们可以通过用标点符号将它们包围起来来在文本中强调它们。AsciiDoc 将这种标记称为*引用的文本*。

引用的文本

例如，在电子邮件中，您可以通过将词语括在星号中来“大声”说出它。

I can't believe it, we *won*!

正如您所料，星号将文本*突出显示*为粗体。您几乎能感受到情感。这是引用（即格式化）文本的一个例子。

术语“引用”在此被广泛用于任何包围文本以施加强调或特殊含义的符号。

AsciiDoc 识别的引用文本形式如下

粗体、斜体和等宽格式语法
bold *constrained* & **un**constrained

italic _constrained_ & __un__constrained

bold italic *_constrained_* & **__un__**constrained

monospace `constrained` & ``un``constrained

monospace bold `*constrained*` & ``**un**``constrained

monospace italic `_constrained_` & ``__un__``constrained

monospace bold italic `*_constrained_*` & ``**__un__**``constrained

当您想在单词边界之外的任何地方引用文本（例如，施加强调）时，您需要将标点符号加倍。

结果：粗体、斜体和等宽文本

粗体*受限*和*不受限*

斜体*受限*和*不受限*

粗斜体*受限*和*不受限*

等宽*受限*和*不受限*

粗体等宽*受限*和*不受限*

斜体等宽*受限*和*不受限*

粗斜体等宽*受限*和*不受限*

任何引用的文本都可以用属性列表作为前缀。第一个位置属性被视为角色。角色可用于应用自定义样式到文本。例如

Type the word [.userinput]#asciidoc# into the search bar.

在转换为 HTML 时，“asciidoc”一词被包装在 <span> 标签中，并且该角色用作元素的 CSS 类

<span class="userinput">asciidoc</span>

您可以使用 CSS 应用文本样式。

您可能不总是希望这些替换发生。在那些情况下，您需要使用标记来转义文本。

防止替换

如果您发现不希望出现的引用文本行为，您可以使用反斜杠或直通宏来阻止它。

Asciidoctor 提供了几种防止替换的方法。

反斜杠转义

要阻止标点符号被解释为格式标记，请在其前面加上反斜杠（\）。如果格式化标点符号以两个字符开头（例如 __），则需要在其前面加上两个反斜杠（\\）。这也是如何防止字符和属性引用被替换的方式。当您的文档被处理时，反斜杠会被删除，因此它不会显示在您的输出中。

\*Stars* will appear as *Stars*, not as bold text.

\&sect; will appear as an entity, not the &sect; symbol.

\\__func__ will appear as __func__, not as emphasized text.

\{two-semicolons} will appear {two-semicolons}, not resolved as ;;.

Asciidoctor 支持几种形式的直通宏。

内联直通宏

一个名为 pass 的内联宏，可用于直通内容。支持可选的替换集。

pass:[content like #{variable} passed directly to the output] followed by normal content.

content with only select substitutions applied: pass:c,a[__<{email}>__]
单个和双个加号

一种特殊的语法，用于防止文本被格式化。仅转义特殊字符以符合输出格式，并且不支持显式替换。

三重加号

一种特殊的语法，用于指定直通内容。不应用任何替换（等同于内联直通宏）并且不支持显式替换。

双美元（已弃用）

一种已弃用的特殊语法，用于指定直通内容。与三重加号一样，不应用任何替换，并且不支持显式替换。

Asciidoctor 不实现块直通宏。相反，您应该使用直通块。

内联传递宏和显式替换

要将短语排除在替换之外并禁用特殊字符的转义，请将其包含在内联直通宏中。例如，这是在从 AsciiDoc 生成 HTML 时将文本格式化为下划线的一种方法

The text pass:[<u>underline me</u>] is underlined.

文本 下划线 是下划线。

如果您想启用临时 quotes 替换，请将 macros 值分配给 subs 并使用内联直通宏。

[subs=+macros] (1)
----
I better not contain *bold* or _italic_ text.
pass:quotes[But I should contain *bold* text.] (2)
----
1 macros 被分配给 subs，这允许块中的任何宏被处理。
2 直通宏被分配了 quotes 值。方括号内的文本将被格式化。

内联直通宏确实会在源代码中引入额外的标记，这可能导致其原始形式无效。然而，它生成的输出在查看器（HTML、PDF 等）中将是有效的。

I better not contain *bold* or _italic_ text.
But I should contain bold text.

内联直通宏还接受用于指定替换的简写值。

  • c = 特殊字符

  • q = 引语

  • a = 属性

  • r = 替换

  • m = 宏

  • p = 后置替换

例如，下面的内联直通宏中分配了引语文本替换值

The text pass:q[<u>underline *me*</u>] is underlined and the word "`me`" is bold.

文本 下划线 我 是下划线，而“我”一词是粗体。

三重加号直通

三重加号直通的工作方式与直通宏非常相似。要将内容排除在替换之外，请将其包含在三重加号（+++）中。

+++content passed directly to the output+++ followed by normal content.

三重加号宏通常用于输出自定义 HTML 或 XML。

The text +++<u>underline me</u>+++ is underlined.

文本 下划线 是下划线。

单加号包围

要将短语排除在替换之外，请将其包含在加号（+）中。

This +*literal*+ will appear as *literal*.

替换

AsciiDoc 还识别符号、箭头和破折号的文本表示。

文本符号替换
名称 语法 Unicode 替换 渲染 备注

版权

 
(C)
 
&#169;

©

注册

 
(R)
 
&#174;

®

商标

 
(TM)
 
&#8482;

™

长破折号

 
--
 
&#8212;

 — 

仅在两个单词字符之间、单词字符和行边界之间，或被空格包围时替换。

当被空格包围时（例如，a -- b），普通空格将被细空格 (&#8201;) 替换。

省略号

 
...
 
&#8230;

…​

单右箭头

 
->
 
&#8594;

→

双右箭头

 
=>
 
&#8658;

⇒

单左箭头

 
<-
 
&#8592;

←

双左箭头

 
<=
 
&#8656;

⇐

印刷体撇号

 
Sam's
 
Sam&#8217;s

Sam’s

打字机撇号会被替换为印刷体（也称为弯曲）撇号。

这种轻微的标点符号并不会削弱文本的可读性。事实上，您可能会认为它使文本更容易阅读。重要的是，这些是您可能已经熟悉的约定。

AsciiDoc 中的标点符号用于创建文档中另一种非常常见的元素，即*列表！*

列表，列表，列表

AsciiDoc 支持三种类型的列表

  1. 无序

  2. 有序

  3. 描述

无序列表和有序列表在结构上非常相似。它们由以不同类型的标记（即项目符号）为前缀的项组成。相比之下，描述列表——也称为变量、标记或术语定义列表——是术语的集合，每个术语都有自己的支持内容。与无序列表和有序列表不同，描述列表很少嵌套，尽管它们经常包含前者。

让我们逐一探索每种列表类型，然后将它们混合在一起。我们还将研究如何将复杂内容放入列表项中。

事物列表

如果您要在电子邮件中创建列表，您会怎么做？碰巧，您会使用与 AsciiDoc 用来查找列表项相同的字符来标记列表项。

在下面的示例中，每个列表项都使用星号（*）标记，这是指定无序列表项的 AsciiDoc 语法。

* Edgar Allan Poe
* Sheri S. Tepper
* Bill Bryson

列表项的第一行文本必须与标记（*）至少保持一个空格的距离。如果您愿意，可以缩进列表项。列表前后需要空行。此外，列表项之间允许但不要求有空行。

渲染的无序列表

  • 埃德加·爱伦·坡

  • 雪莉·S·泰珀

  • 比尔·布莱森

您可以通过在标题前加上句点（.）来为列表添加标题。

.Kizmet's Favorite Authors
* Edgar Allan Poe
* Sheri S. Tepper
* Bill Bryson
带标题的渲染无序列表
Kizmet 的最爱作者

  • 埃德加·爱伦·坡

  • 雪莉·S·泰珀

  • 比尔·布莱森

您是用连字符（-）而不是星号来标记列表项的吗？您猜怎么着？这也行！

- Edgar Allan Poe
- Sheri S. Tepper
- Bill Bryson

您应该将连字符保留给只有单层级的列表，因为连字符标记（-）不适用于嵌套列表。既然我们提到了嵌套列表，让我们进入下一节，学习如何创建多层列表。

分离列表

如果您有相邻的列表，它们会倾向于合并在一起。要强制列表分开，请在两个列表之间插入一个用空行包围的行注释（//）。这里有一个例子，其中行注释中的 - 表示该行作为“列表结束”标记

* Apples
* Oranges

//-

* Walnuts
* Almonds

要嵌套一项，只需在标记前再加一个星号（*），对于每个后续级别再加一个。

.Possible DefOps manual locations
* West wood maze
** Maze heart
*** Reflection pool
** Secret exit
* Untracked file in git repository
渲染的嵌套无序列表
可能的 DefOps 手册位置

  • 西木迷宫

    • 迷宫之心

      • 反射池

    • 秘密出口

  • Git 仓库中未跟踪的文件

在 Asciidoctor 1.5.7 及更早版本中，您最多只能有六（6）个嵌套级别（假设一个级别使用连字符标记）。

自 Asciidoctor 1.5.8 起，您可以将无序列表嵌套到任何深度。但请记住，一些界面会在一定深度后开始展平列表。GitHub 在 10 个嵌套级别后开始展平列表。

* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1

  • 级别 1

    • 级别 2

      • 级别 3

        • 级别 4

          • 级别 5

  • 级别 1

虽然星号的数量代表嵌套级别似乎是这样，但深度并非如此确定。每个唯一遇到的标记都会创建一个新级别。但是，遵循星号数量等于嵌套级别的约定要直观得多。毕竟，我们的目标是使纯文本标记*本身*就可读。

排序事物

有时，我们需要为列表中的项编号。本能可能会告诉您在每项前面加上一个数字，就像在下面的列表中一样

1. Protons
2. Electrons
3. Neutrons

上面的方法有效，但由于编号是显而易见的，因此 AsciiDoc 处理器会在您省略数字时为您插入数字

. Protons
. Electrons
. Neutrons

  1. 质子

  2. 电子

  3. 中子

如果您选择为有序列表使用数字，您必须保持它们的顺序。这与其他轻量级标记语言不同。这是调整列表编号偏移的一种方法。例如，您可以键入

4. Step four
5. Step five
6. Step six

但是，一般来说，最佳实践是使用 start 属性来配置此类事务

[start=4]
. Step four
. Step five
. Step six

要以相反的顺序呈现项，请添加 reversed 选项

[%reversed]
.Parts of an atom
. Protons
. Electrons
. Neutrons
原子的组成部分

  1. 质子

  2. 电子

  3. 中子

您可以通过在行前加上一个点，然后紧跟着文本（不留空格），来为列表添加标题。

这是一个带标题的列表示例

.Parts of an atom
. Protons
. Electrons
. Neutrons
原子的组成部分

  1. 质子

  2. 电子

  3. 中子

您可以通过在每个项前面使用一个或多个点来创建一个嵌套项。

. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3

AsciiDoc 为每个嵌套级别选择不同的编号方案。以下是先前列表的渲染方式

嵌套有序列表

  1. 步骤 1

  2. 步骤 2

    1. 步骤 2a

    2. 步骤 2b

  3. 步骤 3

与无序列表中的星号一样，有序列表中的点数并不代表嵌套级别。但是，遵循此约定要直观得多

点数 = 嵌套级别

同样，我们的目标是使纯文本标记*本身*就可读。

Asciidoctor 努力推断出对我们人类最直观的项之间的关系。这是一个在有序列表中嵌套无序列表的示例

. Linux
* Fedora
* Ubuntu
* Slackware
. BSD
* FreeBSD
* NetBSD

  1. Linux

    • Fedora

    • Ubuntu

    • Slackware

  2. BSD

    • FreeBSD

    • NetBSD

您可以分散项并将嵌套列表缩进，如果这让您更容易阅读

. Linux

  * Fedora
  * Ubuntu
  * Slackware

. BSD

  * FreeBSD
  * NetBSD

下表显示了每个嵌套级别默认使用的编号方案。

按级别的有序列表编号方案
级别 编号方案 示例 CSS 类（HTML 转换器）

1

阿拉伯语

1. 2. 3.

arabic

2

小写字母

a. b. c.

loweralpha

3

小写罗马数字

i. ii. iii.

lowerroman

4

大写字母

A. B. C.

upperalpha

5

大写罗马数字

I. II. III.

upperroman

您可以通过设置其样式（块属性列表中的第一个位置条目）来覆盖任何级别的编号方案。您还可以使用 start 属性设置起始编号

[lowerroman, start=5]
. Five
. Six
[loweralpha]
.. a
.. b
.. c
. Seven

描述列表

描述列表（通常缩写为 dlist）在您需要为一项或多项包含描述或支持文本时很有用。描述列表中的每个项都包括

  • 一项或多项

  • 每个术语后面的分隔符（通常是双冒号，::）

  • 至少一个空格或换行

  • 支持内容（文本、附加块或两者兼有）

这是一个识别计算机部件的描述列表示例

CPU:: The brain of the computer.
Hard drive:: Permanent storage for operating system and/or user files.
RAM:: Temporarily stores information the CPU uses during operation.
Keyboard:: Used to enter text or control items on the screen.
Mouse:: Used to point to and select items on your computer screen.
Monitor:: Displays information in visual form using text and graphics.

默认情况下，每项的内容会显示在描述下方。这是该列表渲染方式的预览

基本描述列表
CPU

计算机的大脑。

硬盘

操作系统和/或用户文件的永久存储。

RAM

在 CPU 运行期间临时存储 CPU 使用的信息。

键盘

用于输入文本或控制屏幕上的项目。

鼠标

用于指向和选择计算机屏幕上的项目。

显示器

以文本和图形的视觉形式显示信息。

如果您希望描述和内容出现在同一行，请将水平样式添加到列表中。

[horizontal]
CPU:: The brain of the computer.
Hard drive:: Permanent storage for operating system and/or user files.
RAM:: Temporarily stores information the CPU uses during operation.
CPU

计算机的大脑。
硬盘

操作系统和/或用户文件的永久存储。
RAM

在 CPU 运行期间临时存储 CPU 使用的信息。

描述列表的内容可以是任何 AsciiDoc 元素。例如，我们可以重写上面的杂货清单，使每个过道成为描述而不是父大纲列表项。

Dairy::
* Milk
* Eggs
Bakery::
* Bread
Produce::
* Bananas
乳制品

  • 牛奶

  • 鸡蛋

面包店

  • 面包

农产品

  • 香蕉

描述列表对空格非常宽容，因此您可以分散各项，甚至缩进内容，如果这让您更容易阅读

Dairy::

  * Milk
  * Eggs

Bakery::

  * Bread

Produce::

  * Bananas

混合列表

最后，您可以在单个混合列表中混合搭配这三种列表类型。Asciidoctor 努力推断出对我们人类最直观的项之间的关系。

这是一个混合了描述、有序和无序列表项的列表

Operating Systems::
  Linux:::
    . Fedora
      * Desktop
    . Ubuntu
      * Desktop
      * Server
  BSD:::
    . FreeBSD
    . NetBSD

Cloud Providers::
  PaaS:::
    . OpenShift
    . CloudBees
  IaaS:::
    . Amazon EC2
    . Rackspace

以下是列表的渲染方式

混合列表
操作系统
Linux

  1. Fedora

    • 桌面

  2. Ubuntu

    • 桌面

    • 服务器

BSD

  1. FreeBSD

  2. NetBSD

云提供商
PaaS

  1. OpenShift

  2. CloudBees

IaaS

  1. Amazon EC2

  2. Rackspace

您也可以在列表项中包含更复杂的内容。

AsciiDoc 可以轻松地在文档中包含链接、图像和其他媒体类型。

您无需做任何事情即可创建指向 URL 的链接。只需将 URL 包含在文档中，AsciiDoc 就会将其转换为链接。

Asciidoctor 在没有任何标记的帮助下识别以下常见方案。

  • http

  • https

  • ftp

  • irc

  • mailto

  • email@email.com

您可以将这些视为隐式宏名称（裸电子邮件地址是特例）。由于下面示例中的 URL 以协议开头（在本例中为*https*后跟冒号），Asciidoctor 在处理时会自动将其转换为超链接。

The homepage for the Asciidoctor Project is https://asciidoctor.org.cn. (1)
1 尾随的句点不会被包含在链接中。

要阻止 URL 自动链接，请在其前面加上反斜杠（\）。

Once launched, the site will be available at \https://example.org.

如果您希望 URL 显示时隐藏方案，请在文档的标题中设置 hide-uri-scheme 属性。

:hide-uri-scheme:

https://asciidoctor.org.cn

当设置 hide-uri-scheme 属性时，上述 URL 将呈现如下

<a href="https://asciidoctor.org.cn">asciidoctor.org</a>

请注意 <a> 元素中缺少*https*。

要将 URL 附加到文本，请将文本括在 URL 末尾的方括号中，从而使其成为 URL 宏

Chat with other Fedora users in the irc://irc.freenode.org/#fedora[Fedora IRC channel].

当 URL 不以常见方案之一开头，或者 URL 不被单词边界包围时，您必须使用 link 宏。link 宏是 URI 宏的更强大版本，您可以将其视为不受限制的宏。URL 前面是 link:，后面是方括号。方括号可能包含可选的链接文本。如果未指定链接文本，则 URL 用作链接文本。在 1.5.7 之前，如果设置了 linkattrs 文档属性，方括号中的文本将被解析为属性，这允许指定窗口名称或角色。自 1.5.7 起，如果等号出现在逗号之后，则会自动解析属性（例如，[link text,window=_blank]）。

链接宏的结构
link:url[optional link text, optional target attribute, optional role attribute]

让我们考虑一个需要使用链接宏（而不是仅仅使用 URI 宏）来展开链接的场景，因为它不与单词边界相邻（即不受限制）。

search/link:https://ecosia.org[Ecosia]

search/Ecosia

如果在此情况下不使用 link: 前缀，URL 宏将不会被解析器检测到。

= Asciidoctor Document Title

Let's view the raw HTML of the link:view-source:asciidoctor.org[Asciidoctor homepage,window=_blank].

让我们查看Asciidoctor 主页的原始 HTML。

由于 _blank 是最常见的窗口名称，我们为其引入了简写。只需在链接文本末尾加上尖括号（^）

Let's view the raw HTML of the link:view-source:asciidoctor.org[Asciidoctor homepage^].
如果您在同一段落中使用尖括号语法多次，您可能需要使用反斜杠转义第一个出现项。

启用属性解析时，您可以为链接添加角色（即 CSS 类）。

Chat with other Asciidoctor users on the https://discuss.asciidoctor.org/[*mailing list*^,role=green].

在邮件列表上与其他 Asciidoctor 用户聊天。

带属性的链接（包括 mailto 链接的主题和正文部分）是 Asciidoctor 的独特功能。当它们启用时，如果链接文本包含逗号，您必须将其用双引号括起来。

如果您想链接到相对于当前文档的外部文件，请在文件名前面使用 link 宏。

link:protocol.json[Open the JSON file]

如果您的文件是 HTML 文件，您可以直接链接到文档中的某个部分，在文件名末尾附加一个哈希（#）后跟该部分的 ID。

link:external.html#livereload[LiveReload]

对于指向相对 AsciiDoc 文档的链接，应使用交叉引用。

交叉引用

指向 AsciiDoc 文档内另一个位置或 AsciiDoc 文档之间的链接称为*交叉引用*（也称为*xref*）。

在 Asciidoctor 中，内联 xref 宏用于创建到具有 ID（无论该 ID 是显式还是自动生成的）的内容元素（节、块或短语）的交叉引用（也称为内嵌或页面引用）。

通过将目标块或节的 ID（或另一个文档的路径及可选锚点）括在双角括号中来创建交叉引用。

使用目标节 ID 的交叉引用
The section <<images>> describes how to insert images into your document.
使用目标节 ID 渲染的交叉引用

《图像》一节描述了如何将图像插入文档。

您还可以通过引用标题来链接到块或节，这称为*自然交叉引用*。标题必须包含至少一个空格字符或至少一个大写字母。（如果您使用的是 Ruby < 2.4，则该大写字母仅限于基本拉丁字符集）。

使用节标题的交叉引用
Refer to <<Internal Cross References>>.
使用节标题渲染的交叉引用

请参阅内部交叉引用。

转换器通常使用目标的 reftext 作为链接的默认文本。解析文档时，reftext 中的属性引用会立即替换。显示 reftext 时，其他 reftext 替换会应用于文本（特殊字符、引号和替换）。

您可以通过在交叉引用的位置指定替代文本来覆盖目标的 reftext。在 ID 之后，添加一个逗号，然后输入您希望交叉引用显示的自定义文本。

带有自定义 xreflabel 文本的交叉引用
Learn how to <<link-macro-attributes,use attributes within the link macro>>.
使用自定义 xreflabel 文本渲染的交叉引用

了解如何 在链接宏中使用属性。

您也可以使用内联 xref 宏，作为双尖括号形式的替代方案。

内联 xref 宏
Learn how to xref:link-macro-attributes[use attributes within the link macro].

交叉引用还可以用于创建指向相对于当前文档的文件的链接。对于指向另一个 AsciiDoc 文档的链接，这是首选方式。

末尾的哈希（#）表示您引用的是文档的顶部。

交叉引用到相对 AsciiDoc 文档的顶部
Refer to <<document-b.adoc#,Document B>> for more information.
交叉引用到相对 AsciiDoc 文档的 HTML 转换结果
Refer to <a href="document-b.html">Document B</a> for more information.

要直接链接到文档中的某个部分，请在哈希（#）后追加该部分的 ID。

交叉引用到相对 AsciiDoc 文档的特定部分
Refer to <<document-b.adoc#section-b,Section B>> for more information.
交叉引用到相对 AsciiDoc 文档某个部分的 HTML 转换结果
Refer to <a href="document-b.html#section-b">Section B</a> for more information.

在这两种情况下，如果您在要引用的文档内部，此语法同样适用。如果您在多个文档中共享相同的链接，这将非常有用。

在从文档间交叉引用创建的链接中，源文件名扩展名将被 outfilesuffix 属性的值替换。要自定义链接目标中使用的文件扩展名，只需更改此属性的值即可。

图像引用类似于链接，因为它们也是对 URL 或文件的引用。当然，区别在于它们会在文档中显示图像。

图像

要将图像包含在自己的行上（即，块图像），请在文件名前面加上 image:: 前缀，并在文件名后面加上方括号。

image::sunset.jpg[]

如果您想指定替代文本，请将其包含在方括号内。

image::sunset.jpg[Sunset]

您还可以为图像指定 ID、标题（即说明）、设置尺寸（即宽度和高度）并使其成为链接。

[#img-sunset]
.A mountain sunset
[link=https://www.flickr.com/photos/javh/5448336655]
image::sunset.jpg[Sunset,300,200]

块图像的标题在渲染时显示在图像下方。以下是预览。

带说明的超链接图像
Sunset
山间日落
图像相对于 imagesdir 文档属性的值进行解析，该属性默认为空值。imagesdir 属性可以是绝对路径、相对路径或基本 URL。如果图像目标是 URL 或绝对路径，则 不 添加 imagesdir 前缀。
您应该使用 imagesdir 属性来避免在每个图像宏中硬编码共享图像路径。

如果您想内嵌包含图像，请改用 image: 前缀（请注意只有一个冒号）。

Press the image:save.png[Save, title="Save"] button.

对于内联图像，可选标题将显示为工具提示。

如果段落和列表是文档的主体，那么标题和章节就是文档的骨架。让我们来探索如何为您的文档构建结构。

标题、标题、标题

AsciiDoc 支持三种类型的标题。

  1. 文档标题

  2. 章节标题

  3. 块标题

所有标题在 AsciiDoc 中都是可选的。本节将定义每种标题类型，并解释如何以及何时使用它们。

文档标题

就像每封电子邮件都有主题一样，每个文档（通常）都有一个标题。标题位于 AsciiDoc 文档的顶部。

文档标题是 AsciiDoc 文档的一个可选功能。

要创建文档标题，请在文档的第一行以一个等号开头，后跟至少一个空格（= ），然后是标题文本。此语法是声明文档标题最简单（因此推荐）的方法。

这是一个文档标题后跟一个缩写段落的示例。

= Lightweight Markup Languages

According to Wikipedia...

文档标题是文档标题的一部分。那么，还有什么可以放在标题中？好问题。

文档标题

请注意前一个示例中标题行和第一个内容行之间的空白行。此空白行将文档标题与文档正文（在此情况下为段落）分开。文档标题是文档标题的一部分。总而言之，文档标题包含标题、作者、修订信息和文档范围的属性。

如果标题行没有以空白行分隔，它将被解释为章节标题，我们稍后将讨论这一点。

您的文档现在有了一个标题，但作者呢？就像每封电子邮件都有发件人一样，每个文档肯定都必须有一个作者。让我们看看如何向标题中添加额外信息，包括作者。

在文档标题下方，可以添加两行可选文本来定义通用文档属性。

第一行

作者姓名和可选电子邮件地址

第二行

可选修订、日期和可选备注

让我们将这些行添加到我们的文档中。

= Lightweight Markup Languages
Doc Writer <doc.writer@asciidoc.org>
v1.0, 2012-01-01

According to Wikipedia...

现在，标题包含文档标题、作者、修订号和日期。这些信息通常将显示为输出文档顶部的格式化标题。

标题（包括文档标题）是非必需的。如果不存在，Asciidoc 处理器将愉快地转换任何存在的内容。标题仅在生成完整文档时使用。它不包含在嵌入式文档的输出中。

文档标题还可以用于定义属性。

文档属性

属性是 AsciiDoc 区别于其他轻量级标记语言的功能之一。您可以使用属性来切换功能或存储可重用或替换内容。

大多数情况下，属性在文档标题中定义。有时可以在内联定义它们，但我们将重点关注更常见的用法。

属性条目由行开头用冒号括起来的名称组成，后跟至少一个空格，然后是内容。内容是可选的。

这是一个存储应用程序版本的属性示例。

= User Guide
Doc Writer <doc.writer@asciidoc.org>
2012-01-01
:appversion: 1.0.0
第一个属性条目与标题的其余部分之间不应有空白行。

现在，您可以在文档中的任何位置（其中执行属性替换）通过将名称括在花括号中来引用此属性。

The current version of the application is {appversion}.

属性也常用于存储 URL，URL 可能很长。这是一个例子。

:fedpkg: https://apps.fedoraproject.org/packages/rubygem-asciidoctor

这是使用中的属性。

Information about the Asciidoctor package for Fedora can found at {fedpkg}.

文档属性还可以用于切换设置或设置控制 AsciiDoc 处理器生成的输出的配置变量。

例如，要在文档中包含目录，可以定义 toc 属性。

:toc:

要取消定义属性，请在名称末尾加上 !。

:linkcss!:

您还可以设置图像（默认：空）、图标（默认：./images/icons）、样式表（默认：./stylesheets）和 JavaScript 文件（默认：./javascripts）的基本路径。

:imagesdir: ./images
:iconsdir: ./icons
:stylesdir: ./styles
:scriptsdir: ./js
属性值也可以在调用 AsciiDoc 处理器时设置和覆盖。我们稍后将探讨此功能。

当您发现自己反复输入相同文本，或者需要经常更新的文本时，请考虑将其分配给文档属性并使用该属性。

随着文档的增长，您将希望将内容分解为章节，就像本指南一样。这可以通过章节标题来实现。

章节标题

章节将文档划分为内容层次结构。在 AsciiDoc 中，章节使用章节标题定义。

章节标题使用与文档标题相同的语法，只是该行可以以两个到六个等号开头，而不是一个等号。等号的数量表示嵌套级别（使用 0 基索引）。

以下是 AsciiDoc 文档（对于文章 doctype，默认）允许的所有章节级别，显示在文档标题下方。

= Document Title (Level 0)

== Level 1 Section

=== Level 2 Section

==== Level 3 Section

===== Level 4 Section

====== Level 5 Section

== Another Level 1 Section
当文档转换为 HTML 5（使用内置的 html5 后端）时，每个章节标题都会成为一个标题元素，标题级别与等号的数量匹配。例如，级别 1 章节（2 个等号）映射到 <h2> 元素。

章节级别不能随意选择。您必须遵循两条规则。

  1. 只有当 doctype 设置为 book 时，文档才能有多个级别 0 的章节。[1]

  2. 嵌套章节时不能跳过章节级别。

例如，以下语法是非法的。

= Document Title

= Illegal Level 0 Section (violates rule #1)

== First Section

==== Illegal Nested Section (violates rule #2)

第一个章节（文档标题之后）之上的内容是前言的一部分。一旦到达第一个章节，内容就与前面的章节关联。

== First Section

Content of first section

=== Nested Section

Content of nested section

== Second Section

Content of second section
除了用于定义单行章节标题的等号标记外，Asciidoctor 还识别 Markdown 中的哈希符号（#）。这意味着 Markdown 文档的大纲可以很好地转换为 AsciiDoc 文档。

要让处理器自动为章节编号，请在文档标题中定义 sectnums 属性。

:sectnums:

您也可以在文档中的任何章节标题上方使用此属性条目来切换自动编号设置。当您想关闭编号时，请在属性名称末尾添加一个感叹号。

:sectnums!:

== Unnumbered Section
前言

文档标题和第一个章节之间的内容称为前言。如果不存在文档标题，则此内容不会被包装在前言章节中。

= Document Title

preamble

another preamble paragraph

== First Section
使用默认的 Asciidoctor 样式表时，此前言将以引导（即，较大字体）的样式渲染。

您还可以为单个元素分配标题。

块标题

您可以为任何段落、列表或分隔块元素分配标题。标题用作元素的说明。在大多数情况下，标题显示在内容上方。如果内容是图形或图像，标题将显示在内容下方。

块标题定义在元素上方的行中。该行必须以点（.）开头，后跟标题文本，中间没有空格。

这是一个带标题的列表示例

.TODO list
- Learn the AsciiDoc syntax
- Install AsciiDoc
- Write my document in AsciiDoc

说起块标题，让我们深入了解块，发现 AsciiDoc 支持哪些类型的块。

AsciiDoc 中的构建块

AsciiDoc 提供了一套不错的组件，用于在文档中包含非段落文本，例如块引用、源代码列表、侧边栏和表格。这些组件被称为分隔块，因为它们被分隔线包围。

分隔块

您已经看到过许多列表块（即代码块）的示例，它们被四条或更多横线分隔。

----
This is an example of a _listing block_.
The content inside is displayed as <pre> text.
----

在分隔块的边界内，您可以输入任何内容或空行。直到找到结束分隔符，块才会结束。块周围的分隔符决定了块的类型、内容的处理和转换方式，以及输出中用于包裹内容的元素。

以下是上面块转换为 HTML 并在浏览器中查看时的样子。

This is an example of a _listing block_.
The content inside is displayed as <pre> text.

这是生成的 HTML 源代码。

<div class="listingblock">
  <div class="content monospaced">
    <pre>This is an example of a _listing block_.
The content inside is displayed as &lt;pre&gt; text.</pre>
  </div>
</div>

您应该注意到内容处理方式的几点。

  • <pre> HTML 标签已转义。

  • 换行符已保留。

  • 短语“listing block”没有斜体，尽管它周围有下划线。

每种类型的块都根据其目的进行处理。字面块不会接收通常应用于段落的全部替换。由于列表块通常用于源代码，因此不希望进行替换。

下表确定了 AsciiDoc 默认提供的分隔块、它们的目的以及对其内容的替换。

名称（样式） 行分隔符 目的 替换

comment

 
////

未在输出中显示的私有注释

none

example

 
====

指定示例内容或定义告诫块

normal

literal

 
....

按原样显示的输出文本

verbatim

listing, source

 
----

按原样显示的源代码或键盘输入

verbatim

open

 
--

匿名块，可以充当任何其他块（除了pass或table）

varies

pass

 
++++

直接传递到输出文档的原始文本

none

quote, verse

 
____

带可选出处的引文或诗歌

normal

sidebar

 
****

显示在文档流外的侧边栏文本

normal

table

 
|===

用于显示表格内容或高级布局

varies
AsciiDoc 允许分隔线长于 4 个字符。不要这样做。维护长分隔线是极其浪费时间的事，更不用说任意且易出错了。使用创建分隔块所需的最小行长度，然后继续撰写内容。读者永远不会看到长分隔符，因为它们不会传递到输出中。

此表显示了上一表中引用的每个替换组执行的替换。

组/替换 Normal Verbatim None

Special chars

Yes

Yes

No

Callouts

No

Yes

No

Quotes

Yes

No

No

Attributes

Yes

No

No

替换

Yes

No

No

Macros

Yes

No

No

Post replacements

Yes

No

No

为了对属性值应用正常替换，请将其括在单引号中。此行为有两个例外：目前，正常替换不应用于 options 和 title 属性值。

您可以使用块元数据来控制块的显示方式。

块元数据

元数据可以分配给任何块。有几种类型的元数据。

  • Title

  • Id（即锚点）

  • Style（第一个未命名块属性）

  • 命名块属性

这是一个包含所有元数据类型的引用块的示例。

.Gettysburg Address
[[gettysburg]]
[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg]
____
Four score and seven years ago our fathers brought forth
on this continent a new nation...

Now we are engaged in a great civil war, testing whether
that nation, or any nation so conceived and so dedicated,
can long endure. ...
____

这是从该块中提取的元数据。

Title

葛底斯堡演说

Id

gettysburg

Style

quote

命名块属性
attribution

亚伯拉罕·林肯

citetitle

在葛底斯堡公墓落成典礼上的演讲

一个块可以有多个块属性行。属性将被聚合。如果存在名称冲突，则最后一个定义的属性生效。

一些元数据用作补充内容，例如标题，而其他元数据，例如样式，则控制块的转换方式。

块伪装

一些块可以伪装成其他块，此功能由块样式控制。块样式是块属性列表中的第一个位置属性。

告诫块

例如，一个示例块可以充当告诫块。

[NOTE]
====
This is an example of an admonition block.

Unlike an admonition paragraph, it may contain any AsciiDoc content.
The style can be any one of the admonition labels:

* NOTE
* TIP
* WARNING
* CAUTION
* IMPORTANT
====

列表和源代码块

在本教程的开头，还记得我们说用传统的文字处理器在文档中插入源代码有多么痛苦吗？它们就是为此设计的。AsciiDoc 不是！

实际上，在 AsciiDoc 中插入源代码非常容易。只需将原始代码放入列表块中即可。

----
require 'asciidoctor'

puts Asciidoctor.convert_file 'mysample.adoc', to_file: false
----

要启用输出中的语法高亮，请将块的样式设置为 source，并在第二个属性位置指定源语言。

[source,ruby]
----
require 'asciidoctor'

puts Asciidoctor.convert_file 'mysample.adoc', to_file: false
----

您甚至可以使用位于单独文件中的源代码。只需使用 AsciiDoc include 指令即可。

[source,ruby]
----
include::example.rb[]
----

为了真正展示 AsciiDoc 对技术文档的适用性，它还支持源代码中的提示。代码提示用于解释源代码行。说明在列表下方指定，并按编号键入。这是一个例子。

[source,ruby]
----
require 'asciidoctor'  # <1>

Asciidoctor.convert_file 'mysample.adoc'  # <2>
----
<1> Imports the library
<2> Reads, parses, and converts the file

以下是渲染时提示的显示方式。

带提示的源代码
require 'asciidoctor'  (1)

puts Asciidoctor.convert_file 'mysample.adoc'  (2)
1 导入库
2 读取、解析并转换文件

开放块

最通用的块是开放块。开放块可以充当任何其他块，除了pass和table。这是一个开放块充当侧边栏的例子。

[sidebar]
.Related information
--
This is aside text.

It is used to present information related to the main content.
--

透传块

AsciiDoc 中的“万能”机制是透传块。顾名思义，此块将块的内容直接传递到输出文档。当您遇到无法使用 AsciiDoc 语法满足的复杂要求时，透传块会非常有用。

例如，假设您想在文档中嵌入 GitHub gist。您可以定义以下透传块。

++++
<script src="https://gist.github.com/piscisaureus/3342247.js"></script>
++++
使用透传块会将您的内容与特定输出格式（如 HTML）绑定。如果您要使用透传块，我们建议使用条件预处理器指令将特定于格式的内容与您打算支持的每个后端关联起来。

分隔符可选

如果内容是连续的（没有被空行打断），您可以省略块分隔符，而是使用段落上方的块样式将其重新用作分隔块类型之一。

此格式常用于单行列表。

[listing]
sudo dnf install asciidoc

或单行引用。

[quote]
Never do today what you can put off 'til tomorrow.

虽然大多数块是线性的，但表格允许您以水平方式布局内容。

表格的新视角

表格是 AsciiDoc 语法中最完善的领域之一。它们易于创建，易于以原始形式阅读，而且也非常复杂。我建议您谨慎使用表格，因为它们会中断您与读者的对话。当它们是呈现信息的最佳方式时，就知道您手中拥有一个强大的工具。

您可以将表格视为一个分隔块，其中包含一个或多个项目符号列表。列表标记是竖线（|）。每个列表代表表格中的一行，并且必须具有相同数量的项目（考虑到任何列或行跨度）。

这是一个简单的表格示例，包含两列三行。

[cols=2*]
|===
|Firefox
|Web Browser

|Ruby
|Programming Language

|TorqueBox
|Application Server
|===

分隔符（|===）内的第一个非空行决定了列数。由于我们将每个列标题放在单独一行上，因此我们必须使用 cols 块属性来明确说明此表格有两列。* 是重复运算符。它表示将列规范重复到其余的列。在这种情况下，它表示不带任何特殊格式（因为没有）跨越 2 列。

通过在表格上设置 header 选项，我们可以使表格的第一行成为标题。

[cols=2*,options=header]
|===
|Name
|Group

|Firefox
|Web Browser

|Ruby
|Programming Language

...
|===

您还可以使用以下简写形式定义 header 选项。

[%header,cols=2*]

或者，我们可以将标题行定义在单行上，并通过空白行与正文行隔开，这样就不需要 cols 和 options 属性了。

|===
|Name |Group

|Firefox
|Web Browser

...
|===

每个项目（即单元格）的内容可以跨越多行，就像 AsciiDoc 中的其他列表一样。与其他列表不同，每个单元格的内容可以包含空行，而无需列表续行将它们连接在一起。当遇到另一个未转义的竖线（|）时，就开始一个新的单元格。

|===
|Name |Group |Description

|Firefox
|Web Browser
|Mozilla Firefox is an open-source web browser.
It's designed for standards compliance,
performance, portability.

|Ruby
|Programming Language
|A programmer's best friend.

...
|===

您可以使用列说明符设置每列的相对宽度，这是一个在 cols 块属性中定义的以逗号分隔的值列表。列表中条目的数量决定了列的数量。

[cols="2,3,5"]
|===
|Name |Group |Description

|Firefox
|Web Browser
|Mozilla Firefox is an open-source web browser.
It's designed for standards compliance,
performance and portability.

|Ruby
|Programming Language
|A programmer's best friend.

...
|===

如果您想在列内容中包含块或列表，可以在列的相对值末尾加上 a（代表 AsciiDoc）。

[cols="2,3,5a"]
|===
|Name |Group |Description

|Firefox
|Web Browser
|Mozilla Firefox is an open-source web browser.
It's designed for:

* standards compliance,
* performance and
* portability.

|Ruby
|Programming Language
|A programmer's best friend.

...
|===

或者，您可以通过在竖线前加上 a 来将 AsciiDoc 样式应用于单个单元格。

a|Mozilla Firefox is an open-source web browser.
It's designed for:

* standards compliance,
* performance and
* portability.

有整套列和单元格说明符可用于格式化表格内容，包括样式和对齐。

AsciiDoc 表格也可以直接从 CSV 数据创建。只需将 format 块属性设置为 csv，然后在块分隔符内插入 CSV 数据，直接插入

[%header,format=csv]
|===
Artist,Track,Genre
Baauer,Harlem Shake,Hip Hop
The Lumineers,Ho Hey,Folk Rock
|===

或使用 include::[] 指令。

[%header,format=csv]
|===
include::tracks.csv[]
|===

Asciidoctor 0.1.3 还识别用于设置 CSV 和 DSV 表格式的简写表示法。表格块分隔符（即 |===）的第一个位置可以被数据分隔符替换，以相应地设置表格格式。

您可以使用逗号（,）替换前导竖线（|）来指定 csv 格式，而不是使用属性。

,===
a,b,c
,===

同样，可以通过用冒号（:）替换前导竖线（|）来指定 dsv 格式。

:===
a:b:c
:===

这是一个非常强大的选项。

AsciiDoc 还能做什么？

我们已经涵盖了 AsciiDoc 语法的大部分功能，但它仍然有更深的内涵。AsciiDoc 对 README 来说足够简单，但足以满足出版商的需求。

以下是 AsciiDoc 语法支持的一些功能。

  • footnotes

  • indexes

  • appendix, preface, dedication, partintro

  • multi-line attributes

  • preprocessor directive (conditional markup)

  • mathematical formulas

  • musical notation

  • diagrams

  • block filters

  • themes

  • custom blocks, macros and output formats

请参阅Asciidoctor 用户手册，继续探索语法和处理器功能。

现在语法知识足够了。您已经创建了第一个 AsciiDoc 文档。现在是时候将文档转换为可演示的格式了。这将让您真正体会到 AsciiDoc 带给您的强大功能。

转换您的文档

虽然 AsciiDoc 语法在原始形式下是可读的，但该格式的预期受众是作家和编辑。读者不会像他们那样欣赏原始文本。美学很重要。您需要应用漂亮的排版，字体大小遵循“黄金比例”，颜色、图标和图像，以给予其应有的尊重。这就是 Asciidoctor 处理器发挥作用的地方（在您完成写作之后）。

Asciidoctor 处理器解析文档并将其翻译成后端格式，如 HTML、ePub、DocBook 或 PDF。Asciidoctor 附带了一套默认的模板，但您可以自定义模板或创建自己的模板以获得您想要的输出。

在使用 Asciidoctor 处理器之前，您必须安装Asciidoctor Ruby Gem。如果您需要帮助安装 gem，请参阅Asciidoctor 安装指南。

将文档转换为 HTML 5

Asciidoctor 提供命令行工具和 Ruby API，用于将 AsciiDoc 文档转换为 HTML 5、Docbook 5.0 和自定义输出格式。

要使用 Asciidoctor 生成 HTML 文档，请在命令行中输入 asciidoctor，然后是您的文档名称。

$ asciidoctor mysample.adoc

在 Asciidoctor 中，html5 后端是默认的，因此生成 HTML 5 文档无需显式指定后端。

Asciidoctor 还提供 Ruby API，因此您可以直接从 Ruby 应用程序生成 HTML 文档。

require 'asciidoctor'

Asciidoctor.convert_file 'mysample.adoc'

或者，您可以将 HTML 输出捕获到变量中，而不是将其写入文件。

html = Asciidoctor.convert_file 'mysample.adoc', to_file: false, header_footer: true
puts html

要生成 DocBook，只需指定 backend 选项。

Asciidoctor.convert_file 'mysample.adoc', backend: 'docbook'

Asciidoctor 的优势之一是它可以输出到多种格式，而不仅仅是 HTML。

将文档转换为 DocBook

尽管用 DocBook 写作是反人道的，但它作为一种可移植文档格式很有用。由于 AsciiDoc 语法是围绕 DocBook 输出设计的，因此转换效果非常好。AsciiDoc 语法中的每种标记都有一个对应的 DocBook 元素。

Asciidoctor 开箱即用地提供了 Docbook 5.0 后端。要将文档转换为 Docbook 5.0，请使用后端标志设置为 docbook5 来调用处理器。

$ asciidoctor -b docbook5 mysample.adoc

现在，一个名为 mysample.xml 的新 XML 文档将出现在当前目录中。

$ ls -1
mysample.adoc
mysample.html
mysample.xml

如果您在 Linux 上，可以使用 Yelp 查看 DocBook 文件。

$ yelp mysample.xml

DocBook 只是 Asciidoctor 工具链中的一个中间格式。您要么将其输入到处理 DocBook 的系统（如publican），要么使用asciidoctor-fopub 工具将其转换为 PDF。

输出 galore

Asciidoctor 处理器生成的输出的自定义程度确实是无穷无尽的。这里我们只是触及了表面。

查看Asciidoctor 用户手册和Asciidoctor 文档页面以了解更多信息。

AsciiDoc 还在哪里得到支持？

在线尝试 AsciiDoc 是最简单的方法。GitHub 存储库/gist 或 Codeberg 存储库中的 AsciiDoc 文档会自动转换为 HTML 并在 Web 界面中渲染。GitForge 存储库/snippets 也得到支持，包括 include::[] 指令。

如果您在 GitHub、GitLab 或 Codeberg 上有一个项目，您可以将 README 或任何其他文档写成 AsciiDoc，GitForge 的界面将显示 HTML 输出供访问者查看。

特别是 Gists，是尝试 AsciiDoc 的绝佳方式。只需创建一个新的 gist，将文件名扩展名命名为 .adoc，然后输入 AsciiDoc 标记。您可以将文档保存为公共或私有。如果您想在不安装任何软件的情况下尝试 AsciiDoc，gist 是一个很好的起点。

虽然 AsciiDoc 语法和工具链还有很多内容需要探索，但您已经足够了解它，可以编写一系列文档，从简单的 README 到全面的用户指南。

总结

用 AsciiDoc 写作不应该比写电子邮件更复杂。您只需要撰写 AsciiDoc 文档，只需打开一个文本编辑器并键入常规段落。只有当您需要额外的语义或格式时，才需要引入标记。当您需要回忆使用什么标点符号时，让您的直觉来指导您。AsciiDoc 语法基于过去几十年计算的久经考验的纯文本约定。希望您同意标记不会影响文本在原始形式下的可读性，因为这是 AsciiDoc 等轻量级标记语言的关键目标。

作为人类，沟通是我们穿越时空联系彼此并传承知识的纽带。AsciiDoc 使您能够专注于沟通，而不是被其他阻碍您的事物分散注意力。将电子邮件的文本复制到文档中，看看如何轻松地将其重新用作文档。几乎立即，您就会找到您的写作禅意，并享受产生有益的体验。

术语表

admonition paragraph

一个带有标签或图标指示其优先级的提示段落。

admonition block

包含复杂内容的告诫块，带有标签或图标指示其优先级。

backend

一组用于将 AsciiDoc 源转换为不同输出格式的模板。

cross reference

文档中一个位置到另一个由锚点标记的位置的链接。

list continuation

单独一行上的加号（+），用于将文本的相邻行连接到列表项。

quoted text

用特殊标点符号括起来的文本，以赋予其强调或特殊含义。

1. 默认 doctype 是 article，它只允许一个级别 0 的章节（即文档标题）。