Asciidoctor 是一个 快速 的文本处理器和发布工具链，它可以将 AsciiDoc 文档转化成 HTML 5、手册、PDF、EPUB 3 和其他格式。
Asciidoctor 还拥有一个由扩展、转换器、构建插件和工具组成的生态系统，可帮助你使用 AsciiDoc 编写和发布文档。
你可以在 https://docs.asciidoctor.org 找到这些项目的文档。
使用 AsciidoctorJ 直接调用 Asciidoctor 的 API 运行在 Java 或者其他基于 Java 语言的虚拟机中。 使用 Asciidoctor.js 运行在 JavaScript 当中。
该文档有如下语言的翻译版：
我们想感谢我们的 赞助商 致力于通过支持此项目来改善技术文档的生态。谢谢赞助商！没有你们的慷慨支持，Asciidoctor 不可能持续下去。
你可以通过 OpenCollective 成为发起人来支持此项目。
AsciiDoc 是语言。 Asciidoctor 是处理器。
Asciidoctor 读取 AsciiDoc 源文档，如下图左侧面板所示，并将其转换为可发布格式，如 HTML 5，如右侧面板所示。
虽然 Asciidoctor 是 Ruby 编写的，但并不是说你一定要使用 Ruby。 你可以使用 AsciidoctorJ 直接调用 Asciidoctor 的 API 运行在 Java 或者其他基于 Java 语言的虚拟机中。 你可以使用 Asciidoctor.js 运行在 JavaScript 当中。
安装 Asciidoctor 处理器只是文档处理体验的开始。 Asciidoctor 使你可以使用扩展和工具的生态系统，从附加的转换器到扩展语法、构建插件，再到集成的写入和预览环境，都有相应的支持：
Asciidoctor 是 AsciiDoc.py 的继承者。 如果你正在使用 AsciiDoc.py，参见 从 AsciiDoc.py 迁移 去学习如何升级到 Asciidoctor。
Asciidoctor 可以在 Linux、macOS 和 Windows 上运行，需要 Ruby 的以下实现之一：
-
CRuby（也被称为 MRI）2.5 - 3.1
-
JRuby 9.1 - 9.3
-
TruffleRuby（GraalVM）
如果你正在使用一个非英语的 Windows 环境，当调用 Asciidoctor 时，你可能会遇到 Encoding::UndefinedConversionError。
为了解决这个问题，我们建议将控制台中的编码更改为 UTF-8：
chcp 65001
一旦你做出了这个改变，你所有的关于 Unicode 的麻烦都将挥之而去。 如果你使用的是 Eclipse 这样的 IDE，请确保将编码设置为 UTF-8。当你在任何地方都使用 UTF-8 时，Asciidoctor 的工作效果最好。
Asciidoctor 在 RubyGems.org 上以 RubyGem（也被称为 gem）的形式打包和分发，被命名为 asciidoctor。 asciidoctor gem 可以使用 Ruby 打包工具（gem 或 bundle）安装在所有主要的操作系统上。 Asciidoctor 还作为 Docker 镜像发行，作为许多 Linux 发行版的软件包发行，以及作为 macOS 的软件包发行（通过 Homebrew 和 MacPorts）。
包管理器安装的 Asciidoctor 版本可能与 Asciidoctor 的最新版本不匹配。 请查阅发行版的软件包存储库，以了解每个发行版打包的版本。
如果你想使用更高版本的 Asciidoctor，参见 gem 安装说明。
在 Ubuntu 等基于 Debian 和 Debian 的发行版上，使用 APT 安装 Asciidoctor。 要安装，打开终端并键入：
$ sudo apt-get install -y asciidoctor
Homebrew 安装好以后，你就可以安装 asciidoctor gem 了。
打开终端并键入：
$ brew install asciidoctor
Homebrew 安装 asciidoctor gem 到一个独有的“前缀”中，它独立于系统的 gem。
安装 MacPorts 后，你就可以通过 Asciidoctor port 安装 asciidoctor gem 了。
打开终端并键入：
$ sudo port install asciidoctor
要在 Windows 上使用 Asciidoctor，你有两个选择：
或者你可以使用 Rubyinstaller，下载它，然后参照 gem 安装说明。
在你使用 gem install 安装 AsciiDoctor 之前，你应该安装 RVM（或者类似的软件）以在 home 目录下安装 Ruby。
然后，你可以安全地使用 gem 命令去安装或更新 Asciidoctor gem，或者其它的 gem 命令。
当使用 RVM,gem 安装在与系统隔离的位置。
（你不应该使用 gem 命令安装系统范围的 gem）
使用 RVM 安装 Ruby 并使用 rvm use 3.0 激活 Ruby 后，打开终端并键入：
$ gem install asciidoctor
如果要安装预发布版本（例如，候选发布版本），请使用：
$ gem install asciidoctor --pre
-
在项目的根目录（或当前目录）中创建一个 Gemfile
-
将
asciidoctorgem 像下面这样加入到 Gemfile 中：source 'https://rubygems.org' gem 'asciidoctor' # or specify the version explicitly # gem 'asciidoctor', '2.0.18'
-
保存 Gemfile
-
打开命令行安装 gem：
$ bundle
要更新 gem，在 Gemfile 指定新版本，再次运行 bundle。
使用 bundle update（没有指定 gem）是不推荐的，因为它也更新了其他的 gem，可能这并不是预期的结果。
如果你使用包管理器来安装 Asciidoctor，你的操作系统可能配置为自动更新，在这种情况下，你不需要手动更新 gem。
如果成功安装 Asciidoctor gem，Asciidoctor 命令行界面（CLI）将可用。
要验证它是否可用，在终端中运行以下命令:
$ asciidoctor --version
你应该在终端中可以看到关于 Asciidoctor 版本和 Ruby 环境的信息。
Asciidoctor 2.0.18 [https://asciidoctor.org] Runtime Environment (ruby 3.0.1p64 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)
asciidoctor 命令允许从命令行（即终端）调用 asciidoctor。
下面的命令转换文件 README.adoc。然后将结果保存到同一目录下的文件 README.html 中。
通过将源文件的扩展名更改为 .html，生成的HTML文件的名称派生自源文件。
$ asciidoctor README.adoc
你可以通过添加各种标志和开关来控制 Asciidoctor 处理器，你可以学习如何使用这些标志和开关：
$ asciidoctor --help
例如，要将文件写入不同的目录，请使用：
$ asciidoctor -D output README.adoc
asciidoctor 帮助手册 提供了 CLI 的完整参考文档。
参考下面的参考资料，了解如何使用 asciidoctor 命令：
Asciidoctor 也提供了一些 API。该API旨在与其他 Ruby 软件（如Rails、GitHub 和 GitLab）以及其他语言，如与 Java（通过 AsciidoctorJ）和 JavaScript （通过 Asciidoctor.js） 要在应用程序中使用 Asciidoctor，首先需要 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[AsciiDoc].'
Asciidoctor.convert content, safe: :safe如果你想要完整的 HTML 文档，请像下面这样启用 header_footer 参数：
content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
html = Asciidoctor.convert content, header_footer: true, safe: :safe如果你需要访问解析后的文档，你可以将转换分解为几个独立的步骤:
content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
document = Asciidoctor.load content, header_footer: true, safe: :safe
puts document.doctitle
html = document.convert你需要注意的是，如果你不喜欢 Asciidoctor 的输出， 你可以改变！ Asciidoctor 支持自定义转换器，可以处理从解析文档到生成输出的转换。 定制输出片段的一种简单方法是使用模板转换器。 模板转换器允许你提供一个 Tilt——以支持使用模板文件来处理转换文档中的任何节点。
不管你怎么做，你都可以 100% 控制输出。 有关如何使用 API 或定制输出的更多信息，请参见:
Asciidoctor 旨在帮助你轻松编写和发布内容。 但没有你的参与，我们做不到! 如果你需要帮助或希望提供反馈，请点击 获取帮助 中所列举的一些资源，这里有一个小结供你参考：
- 聊天室（Zulip）
- 讨论列表（只读，已归档）
- 社交媒体（Twitter）
-
关注 @asciidoctor 或者搜索 #asciidoctor 标签
关于 Asciidoctor 的更多信息和文档可以在该项目的网站上找到。
GitHub 上的 Asciidoctor 组织托管着项目的源代码、issue tracker 和子项目。
- 源代码仓库（Git）
- Issue tracker
-
https://github.com/asciidoctor/asciidoctor/issues
- GitHub 上的 AsciiDoctor 组织
Asciidoctor 的核心项目是由 行为准则 管理的 Asciidoctor 项目社区。参与就代表你就同意遵守这个准则。让我们一起努力，为每个人创造一个受欢迎、专业、包容和安全的环境。
Copyright © 2012-present Dan Allen, Sarah White, Ryan Waldron, and the individual contributors to Asciidoctor. Use of this software is granted under the terms of the MIT License.
参见 LICENSE 以获取完整的许可证信息。
Asciidoctor 由 Dan Allen 和 Sarah White 发起，已经有 很多人 在 Asciidoctor 很棒的社区里为项目作出贡献。该项目于 2012 年由 Ryan Waldron 发起，基于 Nick Hengeveld 为 Git 网站编写的原型。AsciiDoc.py 由 Stuart Rackham 自 2002 年到 2013 年 发起并维护。有很多来自 AsciiDoc.py 社区 的人们为项目作出贡献。
参见 更新日志 查看完整的日志列表。