AsciiDoc 作家指南

你已经看到了很多列表块（即代码块）的例子，它被四个或更多连字符的行包围起来。

在一个界定的区块内，你可以输入任何内容或空行。该区块一直持续到找到结束定界符。区块周围的定界符确定了区块的类型、内容的处理与转换方式，以及在输出中用来包裹内容的元素。

上面的块在转换成HTML并在浏览器中查看时的样子是这样的：

这里是生成的HTML源代码：

您应该注意内容处理时的一些事项：

每种类型的块都根据其目的进行处理。文字块没有接受通常应用于段落的全部替换。由于列表块通常用于源代码，所以不希望使用替换。

以下表格标识了AsciiDoc默认提供的分隔块，它们的用途以及对其内容执行的替换。

这个表格展示了在前面的表格中每个替代组引用执行的替代操作。

为了对属性值应用正常的替换，需要用单引号将其包围起来。但有两个例外情况：目前正常的替换并不适用于`options`和`title`属性值。

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

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

这是一个引用块的示例，其中包含所有类型的元数据：

这是从这个块中提取的元数据：

一些元数据被用作补充内容，比如标题；而其他元数据，比如样式，则控制了块是如何被转换的。

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

如果内容是连续的（没有被空行中断），你可以不使用块定界符，而是在段落上方使用块样式，将其重新定位为其中一个定界块类型。

这种格式通常用于单行列表。

或者单行引用：

虽然大多数块是线性的，表格也能让您能够水平布局内容。

表格是AsciiDoc语法中最精致的领域之一。它们易于创建，在原始形式中易于阅读，而且非常复杂。我建议你尽量少用表格，因为它们会打断你和读者的对话。当它们是呈现信息的最合适方式时，请知道你手中拥有一个强大的工具。

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

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

块定界符(|===)内的第一非空白行决定了列的数量。 因为我们要把每个列标题放在单独的一行，所以必须使用`cols`块属性来明确声明这个表格有两列。 `*`是重复操作符。 其意味着重复其余列的列规格。 在这个例子中，它意味着在2列中重复没有特殊格式（因为没有指定）。

我们可以将表格的第一行设置为标题，方法是在表格上设置`header`选项。

来源

您也可以使用以下简写来定义`header`选项：

另一种方法是，我们可以在表体行上方空出一行来单独定义标题行，这样就不需要`cols`或`options`属性了。

来源

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

来源

您可以使用_column specifiers_—一个在`cols`块属性中定义的由逗号分隔的相对值列表来设置每列的相对宽度。列表中的条目数量决定了列的数量。

来源

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

来源

另外，您可以通过在垂直条前面加上一个`a`来对单个单元格应用AsciiDoc样式：

来源

您可以使用一整套列和单元格指定符来格式化表格内容，包括样式和对齐方式。

AsciiDoc 表格也可以直接从CSV数据创建。 只需将`format`块属性设置为`csv`，并在块定界符内直接插入CSV数据：

来源

或者使用一个`include::[]`指令：

来源

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

您不必使用属性来指定`csv`格式，只需将开头的竖线(|)替换为逗号(,)即可。

同样地，可以通过用冒号(:)替换开头的竖线(|)来指定`dsv`格式。

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

Asciidoctor既提供了一个命令行工具，也提供了一个Ruby API，用于将AsciiDoc文档转换成HTML 5、Docbook 5.0以及自定义的输出格式。

要使用Asciidoctor生成HTML文档，在命令行中键入`asciidoctor`，后跟您的文档名称。

$ asciidoctor mysample.adoc

在Asciidoctor中，*html5*后端是默认选项，因此不需要显式指定后端就可以生成一个HTML 5文档。

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

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

要生成DocBook，只需指定后端选项：

Asciidoctor的一个优点是它能输出多种格式，不仅仅是HTML。

尽管用DocBook写作不太人性化，但它作为一种便携式文档格式还是很有用的。由于AsciiDoc的语法设计是以DocBook的输出为目的，所以转换的效果非常好。对于AsciiDoc语法中的每一种标记，都有相应的DocBook元素。

Asciidoctor 自带了一个 Docbook 5.0 的后端支持。要将文档转换为 Docbook 5.0，需要调用处理器，并将后端标志设置为 docbook5：

$ asciidoctor -b docbook5 mysample.adoc

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

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

如果你使用的是Linux系统，你可以使用Yelp来查看DocBook文件：

$ yelp mysample.xml

DocBook仅仅是Asciidoctor工具链中的一种中间格式。 你可以将其输入一个处理DocBook的系统（比如https://fedorahosted.org/publican[publican]），或者你可以使用https://github.com/asciidoctor/asciidoctor-fopub#readme[asciidoctor-fopub tool]将其转换为PDF。

你对Asciidoctor处理器生成的输出进行的自定义真的是没有尽头的。我们在这里仅仅触及了表面。

查看https://asciidoctor.org/docs/user-manual[Asciidoctor 用户手册]和https://asciidoctor.org/docs[Asciidoctor 文档页面]了解更多信息。

最简单尝试AsciiDoc的方式是在线操作。在GitHub仓库中的AsciiDoc文档/gist或Codeberg仓库会自动转换为HTML并在网页界面中渲染。GitLab仓库/snippets同样也支持——包括`include::[]`指令。

如果你在GitHub、GitLab或Codeberg上有一个项目，你可以用AsciiDoc编写README或者其他任何文档，Git forge的界面将会为访问者显示HTML输出。

Gists是一个用来尝试AsciiDoc的绝佳方式。只需要创建一个新的gist，将文件命名为扩展名`.adoc`，并输入AsciiDoc标记。你可以将文档保存为公开或私密。如果你想在不安装任何软件的情况下尝试AsciiDoc，使用gist是一个很好的起点。

虽然AsciiDoc语法和工具链还有很多需要探索的地方，但你对它的了解已经足够编写各种文档了，从简单的自述文件到全面的用户指南都可以。