第 6 章. Asciidoctor 入门

6.1. 概述

在计算机的早期，电子文本很简单。有一些字符集，比如 ASCII 或 EBCDIC，仅此而已。文本就是文本，你看到的就是你得到的。没有装饰，没有格式，没有智能。

不可避免地，这还不够。当文本以机器可用的格式存在时，机器应该能够智能地使用和操作它。作者希望指出某些短语应该被强调，或者添加到词汇表中，或者被制成超链接。文件名可以在屏幕上以“打字机”风格的字体显示，但在打印时显示为“斜体”，或者任何其他无数的呈现选项。

人们曾一度希望人工智能 (AI) 会使这变得容易。计算机将阅读文档并自动识别关键短语、文件名、读者应该输入的文本、示例等等。不幸的是，现实生活并没有那么顺利，计算机在能够有意义地处理文本之前仍然需要帮助。

更确切地说，他们需要帮助识别是什么。考虑这段文本

要删除 /tmp/foo，请使用 rm(1)。

% rm /tmp/foo

读者很容易看出哪些部分是文件名，哪些部分是应该输入的命令，哪些部分是对手册页的引用，等等。但是，处理文档的计算机无法可靠地确定这一点。为此，我们需要标记。

前面的示例实际上在本文档中以这种方式表示

To remove */tmp/foo*, use man:rm[1].

[source,shell]
----
% rm /tmp/foo
----

6.2. 标题

Asciidoctor 支持六个标题级别。如果文档类型为 article，则只能使用一个级别 0 (=)。如果文档类型为 book，则可以有多个级别 0 (=) 标题。

这是一个 article 中标题的示例。

= Document Title (Level 0)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

===== Level 4 Section Title

====== Level 5 Section Title

== Another Level 1 Section Title

嵌套部分时，不能跳过部分级别。

以下语法不正确。

= Document Title

== Level 1

==== Level 3

6.3. 段落

段落不需要在 AsciiDoc 中进行特殊标记。段落由一个或多个连续的文本行定义。要创建一个新段落，请留下一行空白。

例如，这是一个包含两个段落的标题。

= This is the heading

This is the first paragraph.
This is also the first paragraph.

And this is the second paragraph.

6.4. 列表

Asciidoctor 支持几种类型的列表，最常见的是 ordered 和 unordered。有关列表的更多信息，请参阅 AsciiDoc 语法快速参考。

6.4.1. 有序列表

要创建一个有序列表，请使用 . 字符。

例如，这是一个有序列表。

. First item
. Second item
.. Subsecond item
. Third item

这将被渲染为。

第一项
第二项
1. 次级第二项
第三项

6.4.2. 无序列表

要创建一个无序列表，请使用 * 字符。

例如，这是一个无序列表。

* First item
* Second item
** Subsecond item
* Third item

这将被渲染为。

第一项
第二项
- 次级第二项
第三项

6.5. 链接

6.5.1. 外部链接

要指向另一个网站，应该使用 link 宏。

link:https://freebsd.ac.cn[FreeBSD]

正如 Asciidoctor 文档所述，当目标以 URL 模式（如 https）开头时，link 宏不是必需的。但是，为了确保 Asciidoctor 正确地渲染链接，特别是对于日语等非拉丁语言，最好还是这样做。

6.5.2. 指向另一本书或文章的链接

要指向另一本书或文章，应该使用 Asciidoctor 变量。例如，如果我们在 cups 文章中，并且我们想要指向 ipsec-must，则应该使用以下步骤。

从 ~/doc/shared 文件夹中包含 urls.adoc 文件。
```
include::shared/{lang}/urls.adoc[]
```
然后使用 Asciidoctor 变量创建一个指向 ipsec-must 文章的链接。
```
extref:{ipsec-must}[IPSec-Must article]
```
这将被渲染为。
IPSec-Must 文章

extref 宏被定义为一个扩展。它旨在跨不同输出渲染正确的链接

6.5.3. 指向同一文件或同一本书中其他文件的链接

书籍被结构化在不同的目录中，以保持合理的布局。要从一本书的某个子目录创建一个指向同一本书另一个子目录的链接，请使用 crossref 宏

crossref:doc-build[documentation-makefile, This link]

这将被渲染为

此链接

crossref 宏被定义为一个扩展。它旨在跨不同输出渲染正确的链接

对于文档内链接也使用 crossref 宏。虽然写下当前文档的名称可能不方便，但它确保在不同输出中渲染正确的链接

不要使用 xref 宏或其快捷方式 << >>。它们在所有输出格式中效果都不好。

6.6. 图像和图标

图像和图标在增强整体用户体验方面起着至关重要的作用。这些视觉元素被战略性地整合进来，以传达信息，阐明概念，并提供一个引人入胜的视觉界面。

6.6.1. 图像

图像有助于说明复杂的概念，使其更易于用户访问。

第一步是将图像添加到路径中的图像目录中

~/website/static/images/ 用于网站。
~/documentation/static/images/ 用于文档。

例如，要将新图片添加到 FreeBSD 安装过程中，该图片将保存到路径 ~/documentation/static/images/books/handbook/bsdinstall/new-image3.png。

下一步将是配置 Asciidoctor 属性 images-path 和 imagesdir。

我们将以 FreeBSD 版本工程文章的标题为例。

= FreeBSD Release Engineering
:doctype: article

[...]

:images-path: articles/freebsd-releng/ (1)


[...]

:imagesdir: ../../../images/{images-path} (2)

[...]

1	引用 /static/images 文件夹内的路径。
2	引用 Asciidoctor 属性。

一旦图片位于正确路径并且 Asciidoctor 属性已在文档中配置，就可以使用 image 宏。

这是一个示例

image::new-image3.png[New step in the FreeBSD install process]

为了提高可访问性，必须为每个图片添加描述性文本。

6.6.2. 图标

图标充当直观的符号，便于快速识别和导航。

使用图标的第一步是在每个文档的顶部，将 icons 属性添加到 Asciidoctor 属性部分。

:icons: font

设置 Asciidoctor 图标属性后，就可以添加 Font Awesome 支持的图标。

这是一个关于如何使用 envelope 图标的示例

icon:envelope[link=mailto:[email protected], title="contact"]

为了提高网站的可访问性，title 属性是必需的。

6.7. 结论

这是 Asciidoctor 入门的结论。由于篇幅和复杂性的原因，一些内容没有深入探讨（甚至没有提及）。

最后修改时间：2024 年 9 月 22 日，作者：Fernando Apesteguía

首页