使用 AsciiDoc 生成 HTML

Asciidoctor 的默认输出格式是 HTML（特别是 HTML 5）。这意味着当您在没有任何参数的情况下运行 Asciidoctor 时，它将生成 HTML。本页面将解释如何使用 Asciidoctor 将 AsciiDoc 转换为 HTML。

后端和转换器

Asciidoctor 内置的 HTML 转换器已注册用于 html 和 html5 后端。HTML 转换器生成 HTML 5，并使用 CSS3 进行样式设置。它可能包含 JavaScript 来支持其他集成，例如客户端语法高亮。

后端名称	`html`, `html5`
转换器类	`Asciidoctor::Converter::Html5Converter`
输出格式	HTML
输出文件扩展名	.html

内置 HTML 转换器生成的独立 HTML 文档从 Google Fonts 加载 Web 字体，然后由默认样式表引用。默认样式表使用 Web 字体来确保文档在不同平台上的渲染效果一致。有人担心 Google Fonts 不符合 GDPR。如果这成为问题，您可以选择不使用 Google Fonts。这样做后，默认样式表将恢复使用通用字体系列（例如，sans-serif），这些字体系列由您的浏览器映射到系统字体。其结果是，由于依赖于系统字体，文档的外观将有所不同且依赖于系统。

如果后端名称以 x 为前缀（例如 xhtml），转换器将生成 XHTML，即 HTML 的 XML 变体。

生成 HTML

在本节中，我们将创建一个示例文档，然后使用 Asciidoctor 内置的 HTML 转换器对其进行处理和转换。

创建并保存 AsciiDoc 文档

要遵循以下步骤，请使用您自己的 AsciiDoc 文件，或将示例 1 的内容复制到一个新的纯文本文件中。

示例 1. my-document.adoc

= The Dangers of Wolpertingers
:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger

Don't worry about gumberoos or splintercats.
Something far more fearsome plagues the days, nights, and inbetweens.
Wolpertingers.

== Origins

Wolpertingers are {url-wolpertinger}[ravenous beasts].

请确保文件以 .adoc 文件扩展名保存。

将 AsciiDoc 文档转换为 HTML

从命令行将 my-document.adoc 转换为 HTML

打开终端。
切换到包含 my-document.adoc 文档的目录
使用 asciidoctor 命令调用 Asciidoctor 处理器，后跟文档名称。
$ asciidoctor my-document.adoc
请记住，Asciidoctor 的默认转换器是 html5，因此无需使用 -b 命令指定它。
您不会在控制台看到任何消息打印出来。键入 ls 查看目录中的文件，或在文件管理器中导航到该目录。您应该会看到一个名为 my-document.html 的新文件。
$ ls my-document.adoc my-document.html
Asciidoctor 从输入文档的名称推导出输出文档的名称。
在您的网络浏览器中打开 my-document.html。您的文档应如下所示。

文档的文本、标题和链接通过嵌入在 HTML 输出中的默认 Asciidoctor 样式表进行样式设置。因此，您可以将 my-document.html 保存到任何计算机，其外观都将保持一致。
如果您想在终端中预览 HTML，可以使用以下命令代替
```
$ asciidoctor my-document.adoc -o - | w3m - -T text/html
```

生成 XHTML

后端名称	`xhtml`, `xhtml5`
转换器类	`Asciidoctor::Converter::Html5Converter`
输出格式	HTML 的 XML 变体
输出文件扩展名	.html

使用 xhtml5 后端选项生成 XHTML

$ asciidoctor -b xhtml5 my-document.adoc

要在使用转换器模板时生成 XHTML 而不是 HTML，请将 htmlsyntax 属性设置为 xml，同时保留后端选项

使用自定义模板生成 XHTML

$ asciidoctor -T /path/to/templates -b slides -a htmlsyntax=xml my-document.adoc

黑色盒子解码：XHTML 和 htmlsyntax

XHTML 输出是内置 HTML5 转换器的特殊模式。它通过在后端值前添加 x（例如 xhtml 或 xhtml5）来激活。此提示会隐式地将 htmlsyntax 属性设置为 xml 值，而该属性通常的值为 html。

对于所有其他转换器，htmlsyntax 属性不会显式设置。如果您希望用 Slim 或 Haml 编写的转换器模板输出 XHTML 而不是默认的 HTML，则需要显式将 htmlsyntax 属性设置为 xml。Asciidoctor 会通过将 :format 选项设置为 :html5 来将此偏好传递给 Slim 或 Haml 模板引擎。