Asciidoctor

一个快速的文本处理器和发布工具链，用于将 AsciiDoc 转换为 HTML5、DocBook 及更多。

从 RubyGems 下载 gem从 GitHub 查看源代码
= Hello, AsciiDoc!
Doc Writer <doc@example.com>

An introduction to http://asciidoc.org[AsciiDoc].

== First Section

* item 1
* item 2

[source,ruby]
puts "Hello, World!"

Asciidoctor 是一个快速、开源、基于 Ruby 的文本处理器，用于解析 AsciiDoc® 成文档模型，并将其转换为 HTML 5、DocBook 5、手册页、PDF、EPUB 3 及其他输出格式。

Asciidoctor 还拥有一个由扩展、转换器、构建插件和工具组成的生态系统，可以帮助您编写和发布用 AsciiDoc 编写的内容。您可以在 https://docs.asciidoctor.org.cn 找到这些项目的文档。

除了在 Ruby 上运行之外，Asciidoctor 还可以通过 AsciidoctorJ 在 JVM 上执行，或者通过 Asciidoctor.js 在任何 JavaScript 环境中执行。

关键文档

赞助商

我们要感谢我们的 赞助商，感谢他们通过支持本项目来致力于提升技术文档的水平。谢谢你们，赞助商！没有你们慷慨的支持，Asciidoctor 就不可能实现。

您可以通过 OpenCollective 成为赞助商来支持本项目。

AsciiDoc 处理和内置转换器

AsciiDoc 是语言。
Asciidoctor 是处理器。

Asciidoctor 读取 AsciiDoc 源文件（如下图左侧面板所示），并将其转换为可发布格式，例如 HTML 5（如下图右侧面板所示）。

Preview of AsciiDoc source and corresponding rendered HTML

Asciidoctor 默认提供三种输出格式的内置 转换器：HTML 5、DocBook 5 和 man page（手册页的缩写）。PDF 和 EPUB 3 等其他转换器由单独的 gem 提供。Asciidoctor 还提供开箱即用的 HTML 体验，配有 默认样式表 和内置集成，如 Font Awesome（用于图标）、highlight.js、Rouge 和 Pygments（用于源代码高亮），以及 MathJax（用于 STEM 处理）。

Asciidoctor 生态系统

尽管 Asciidoctor 是用 Ruby 编写的，但这并不意味着您必须使用 Ruby 才能使用它。Asciidoctor 可以通过 AsciidoctorJ 在 JVM 上执行，或者在任何 JavaScript 环境（包括浏览器）中使用 Asciidoctor.js 执行。

安装 Asciidoctor 处理器只是您发布体验的开始。Asciidoctor 让您可以访问由扩展和工具组成的生态系统，包括附加转换器、扩展语法、构建插件以及集成的写作和预览环境。

Asciidoctor 是 AsciiDoc.py 的后继者。如果您正在使用 AsciiDoc.py，请参阅 从 AsciiDoc.py 迁移，了解如何升级到 Asciidoctor。

要求

Asciidoctor 可在 Linux、macOS 和 Windows 上运行，并需要以下其中一个 Ruby 实现：

  • CRuby (又名 MRI) 2.3 - 3.3

  • JRuby 9.1 - 9.4

  • TruffleRuby (GraalVM)

如果您使用的是非英语的 Windows 环境，在调用 Asciidoctor 时可能会遇到 Encoding::UndefinedConversionError。为解决此问题，我们建议将默认的外部和内部字符编码覆盖为 utf-8。您可以通过设置 RUBYOPT 环境变量来实现：

RUBYOPT="-E utf-8:utf-8"

做出此更改后，您所有的 Unicode 问题都应该迎刃而解。

如果您使用 Eclipse 等 IDE，请确保在那里也将编码设置为 UTF-8。Asciidoctor 经过优化，可以默认使用 UTF-8 编码。

安装

Asciidoctor 被打包并分发到 RubyGems.org，作为名为 asciidoctor 的 RubyGem（又名 gem）。可以使用 Ruby 包管理工具（gem 或 bundle）在所有主流操作系统上安装 asciidoctor gem。Asciidoctor 还以 Docker 镜像、众多 Linux 发行版的包以及 macOS 包（通过 Homebrew 和 MacPorts）的形式分发。

Linux 包管理器

包管理器安装的 Asciidoctor 版本可能与 Asciidoctor 的最新版本不符。请查阅您发行版的包存储库，了解每个发行版发布版本所打包的版本。

如果您想使用比包管理器安装的版本更新的 Asciidoctor 版本，请参阅 gem 安装说明。

apk (Alpine Linux)

要在 Alpine Linux 上安装 gem，请打开终端并输入：

$ sudo apk add asciidoctor

pacman (Arch Linux)

要在基于 Arch 的发行版上安装 gem，请打开终端并输入：

$ sudo pacman -S asciidoctor

APT

在 Debian 和基于 Debian 的发行版（如 Ubuntu）上，使用 APT 安装 Asciidoctor。要安装包，请打开终端并输入：

$ sudo apt-get install -y asciidoctor

DNF

在基于 RPM 的 Linux 发行版（如 Fedora、CentOS 和 RHEL）上，使用 DNF 包管理器安装 Asciidoctor。要安装包，请打开终端并输入：

$ sudo dnf install -y asciidoctor

macOS

Homebrew

您可以使用 macOS 包管理器 Homebrew 来安装 Asciidoctor。如果您没有在电脑上安装 Homebrew，请先完成 安装说明。

安装 Homebrew 后，您就可以安装 asciidoctor gem 了。打开终端并输入：

$ brew install asciidoctor

Homebrew 将 asciidoctor gem 安装到一个独立的、与系统 gem 分离的前缀中。

MacPorts

您也可以使用 macOS 的另一个包管理器 MacPorts 来安装 Asciidoctor。如果您没有在电脑上安装 MacPorts，请先完成 安装说明。

安装 MacPorts 后，您就可以通过 Asciidoctor 端口 安装 asciidoctor gem 了。打开终端并输入：

$ sudo port install asciidoctor

Windows

要在 Windows 上使用 Asciidoctor，您有两个选择。

Chocolatey

如果您已经在机器上使用 chocolatey，您可以使用：

choco install ruby

然后按照 gem 安装说明 进行操作。

Rubyinstaller

或者，您可以使用 Rubyinstaller，下载适用于您 Windows 版本的安装包，安装完成后，继续执行 gem 安装说明。

gem install

在使用 gem install 安装 Asciidoctor 之前，您应该设置 RVM（或类似工具），以便在您的主目录（即用户空间）中安装 Ruby。然后，您可以安全地使用 gem 命令来安装或更新 Asciidoctor gem，或任何其他 gem。在使用 RVM 时，gem 会安装在与系统隔离的位置。（您永远不应该使用 gem 命令来安装全局 gem）。

使用 RVM 安装 Ruby 并激活它（例如 rvm use 3.0）后，打开终端并输入：

$ gem install asciidoctor

如果您想安装预发布版本（例如，发布候选版），请使用：

$ gem install asciidoctor --pre

Docker

请参阅 使用 Docker 安装 Asciidoctor。

Bundler

  1. 在项目的根文件夹（或当前目录）中创建一个 Gemfile：

  2. 像这样将 asciidoctor gem 添加到您的 Gemfile 中：

    source 'https://rubygems.org.cn'
gem 'asciidoctor'
# or specify the version explicitly
# gem 'asciidoctor', '2.0.23'

  3. 保存 Gemfile

  4. 打开终端并使用以下命令安装 gem：

    $ bundle

要升级 gem，请在 Gemfile 中指定新版本并再次运行 bundle。不建议使用 bundle update（不指定 gem）来更新，因为它还会更新其他 gem，这可能不是您想要的结果。

升级

如果您是使用包管理器安装的 Asciidoctor，您的操作系统很可能配置为自动更新包，在这种情况下，您无需手动更新 gem。

apk (Alpine Linux)

要升级 gem，请使用：

$ sudo apk add -u asciidoctor

APT

要升级 gem，请使用：

$ sudo apt-get upgrade -y asciidoctor

DNF

要升级 gem，请使用：

$ sudo dnf update -y asciidoctor

Homebrew (macOS)

要升级 gem，请使用：

$ brew update
$ brew upgrade asciidoctor

MacPorts (macOS)

要升级 gem，请使用：

$ sudo port selfupdate
$ sudo port upgrade asciidoctor

gem install

如果您之前是使用 gem 命令安装的 Asciidoctor，当新版本发布时，您需要手动升级 Asciidoctor。您可以通过输入以下命令来升级 gem：

$ gem install asciidoctor

当您使用 gem install 安装新版本的 gem 时，您会得到多个已安装的版本。使用以下命令删除旧版本：

$ gem cleanup asciidoctor

用法

如果 Asciidoctor gem 成功安装，asciidoctor 命令行界面 (CLI) 将在您的 PATH 中可用。要验证它是否可用，请在终端中运行以下命令：

$ asciidoctor --version

您应该会在终端中看到有关 Asciidoctor 版本和您的 Ruby 环境的信息。

Asciidoctor 2.0.23 [https://asciidoctor.org.cn]
Runtime Environment (ruby 3.0.1p64 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)

命令行界面 (CLI)

asciidoctor 命令允许您从命令行（即终端）调用 Asciidoctor。

以下命令将 README.adoc 文件转换为 HTML，并将结果保存在同一目录下的 README.html 文件中。生成的 HTML 文件名是通过更改源文件的文件扩展名为 .html 来派生的。

$ asciidoctor README.adoc

您可以通过添加各种标志和开关来控制 Asciidoctor 处理器，有关这些信息，您可以使用：

$ asciidoctor --help

例如，要将文件写入不同的目录，请使用：

$ asciidoctor -D output README.adoc

asciidoctor 手册页提供了命令行界面的完整参考。

请参阅以下资源，以了解更多关于如何使用 asciidoctor 命令的信息：

Ruby API

Asciidoctor 还提供了一个 API。该 API 用于与其他 Ruby 软件（如 Rails、GitHub 和 GitLab）以及其他语言（如 Java（通过 AsciidoctorJ）和 JavaScript（通过 Asciidoctor.js））集成。

要在您的应用程序中使用 Asciidoctor，您首先需要 require 该 gem：

require 'asciidoctor'

然后，您可以使用以下命令将 AsciiDoc 源文件转换为 HTML 文件：

Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe
通过 API 使用 Asciidoctor 时，默认的安全模式是 :secure。在安全模式下，许多核心功能被禁用，包括 include 指令。如果您想启用这些功能，您需要明确将安全模式设置为 :server（推荐）或 :safe。

您还可以使用以下命令将 AsciiDoc 字符串转换为可嵌入的 HTML（用于插入到 HTML 页面中）：

content = '_Zen_ in the art of writing https://asciidoctor.org.cn[AsciiDoc].'
Asciidoctor.convert content, safe: :safe

如果您需要完整的 HTML 文档，请像这样启用 header_footer 选项：

content = '_Zen_ in the art of writing https://asciidoctor.org.cn[AsciiDoc].'
html = Asciidoctor.convert content, header_footer: true, safe: :safe

如果您需要访问解析后的文档，可以将转换分成几个独立的步骤：

content = '_Zen_ in the art of writing https://asciidoctor.org.cn[AsciiDoc].'
document = Asciidoctor.load content, header_footer: true, safe: :safe
puts document.doctitle
html = document.convert

请记住，如果您不喜欢 Asciidoctor 生成的输出，您可以更改它！ Asciidoctor 支持自定义转换器，这些转换器可以处理从解析的文档到生成输出的转换。

一种轻松自定义输出的方法是使用模板转换器。模板转换器允许您提供一个 Tilt 支持的模板文件来处理文档中任何节点的转换。

无论您采用哪种方式，您都可以完全控制输出。有关如何使用 API 或自定义输出的更多信息，请参阅：

贡献

我们一直欢迎新贡献者！如果您在源代码、文档或网站内容中发现错误或遗漏，请随时提交 issue 或发起 pull request 来进行修复。

以下是您可以贡献的一些方式：

  • 使用预发布（alpha、beta 或预览）版本

  • 报告 bug

  • 建议新功能

  • 编写或编辑文档

  • 编写带有测试的代码——任何补丁都不嫌小。

    • 修复拼写错误

    • 添加注释

    • 清理不一致的空格

    • 编写测试！

  • 重构代码

  • 修复 issue

  • 审查补丁

CONTRIBUTING.adoc 文件提供了关于如何创建、样式化和提交 issue、功能请求、代码和文档到 Asciidoctor 的信息。

获取帮助

Asciidoctor 的开发旨在帮助您轻松编写和发布内容。但没有您的反馈，我们是做不到的！我们鼓励您在讨论列表、Twitter 或聊天室中提问并讨论项目的任何方面。

聊天 (Zulip)

https://asciidoctor.zulipchat.com

讨论列表 (Nabble)

https://discuss.asciidoctor.org

Twitter

关注 @asciidoctor 或搜索 #asciidoctor 标签

GitHub 上的 Asciidoctor 组织托管了项目的源代码、issue 跟踪器和子项目。

源代码库 (git)

https://github.com/asciidoctor/asciidoctor

Issue 跟踪器

https://github.com/asciidoctor/asciidoctor/issues

GitHub 上的 Asciidoctor 组织

https://github.com/asciidoctor

行为准则

核心 Asciidoctor 项目遵循 Asciidoctor 项目社区的行为准则。通过参与，您同意遵守此准则。让我们共同努力，为所有人创造一个受欢迎、专业、包容和安全的环境。

版本和发布策略

本项目遵循语义化版本控制（major.minor.patch）。通常，补丁版本仅针对当前次要版本发布。但是，为了解决安全漏洞和其他高优先级问题，会根据具体情况进行例外处理。

版权 © 2012-至今 Dan Allen、Sarah White、Ryan Waldron 以及 Asciidoctor 的个人贡献者。此软件的使用根据 MIT 许可条款授予。

请参阅 LICENSE 以获取完整的许可文本。

作者

Asciidoctor 由 Dan Allen 和 Sarah White 领导，并得到了 Asciidoctor 社区众多个人贡献者的支持。该项目于 2012 年由 Ryan Waldron 基于 Nick Hengeveld 为 Git 网站编写的原型而启动。

AsciiDoc.py 由 Stuart Rackham 从 2002 年至 2013 年启动和维护，并得到了 AsciiDoc.py 社区众多个人的贡献。

商标

AsciiDoc® 和 AsciiDoc Language™ 是 Eclipse Foundation, Inc. 的商标。