转换你的第一个 AsciiDoc 文件

假设

  • 你已安装 Asciidoctor。

  • 你已确认 Asciidoctor 命令行界面 (CLI) 在你的 PATH 中可用。

在本页中，你将学习如何在 AsciiDoc 文档上运行 Asciidoctor 并将其转换为 HTML。

使用默认转换器生成 HTML

让我们从一个 AsciiDoc 文档开始，使用 Asciidoctor 的默认转换器和样式表生成 HTML 5。

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

    示例 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].

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

  3. 打开终端，并切换 (cd) 到保存 AsciiDoc 文档的目录。

    $ cd directory-name

  4. 使用 asciidoctor 命令调用 Asciidoctor，后跟 AsciiDoc 文档的文件名。由于 HTML 5 是 Asciidoctor 的默认输出，因此我们无需指定转换器。

    $ asciidoctor my-document.adoc

    只要文档不包含任何语法错误，你的终端就不会显示任何消息。

  5. 输入 ls 列出目录中的文件。

    $ ls
my-document.adoc  my-document.html

    你应该会看到一个名为 my-document.html 的新文件。Asciidoctor 从输入文档的名称派生输出文件的名称。

  6. 在你的网络浏览器中打开 my-document.html。转换后的文档应该如下面的示例所示。

    my document

    文档的文本、标题和链接由默认的 Asciidoctor 样式表进行样式化，该样式表嵌入在 HTML 输出中。因此，你可以将 my-document.html 保存到任何计算机上，它都会显示相同的内容。

通用文档中的大多数示例都使用 CLI，但通常可以在 使用 API 处理 AsciiDoc 下找到相应的 API 示例。