Asciidoctor 是一个 快速 文本处理器和发布工具链，它可以将 AsciiDoc 文档转化成 HTML5、 DocBook 5 (或 4.5) 以及其他格式。 Asciidoctor 由 Ruby 编写，打包成 RubyGem，然后发布到 RubyGems.org 上。 这个 gem 还被包含道几个 Linux 发行版中，其中包括 Fedora、Debian 和 Ubuntu。 Asciidoctor 是开源的，https://github.com/asciidoctor/asciidoctor[代码托管在 GitHub]，并且是以 MIT 协议授权。
使用 JRuby 可以让 Asciidoctor 运行在 Java 虚拟机上。 使用 AsciidoctorJ 就可以让 Java 或者其他 Java 虚拟机语言直接调用 Asciidoctor API。 基于 AsciidoctorJ 有好多好多插件可用，这些插件可以将 Asciidoctor 整合到 Apache Maven，Gradle 或 Javadoc 构建中。
Asciidoctor 也可以运行在 JavaScript 上。 我们可以使用 Opal 将 Ruby 源码编译成 JavaScript 并生成 Asciidoctor.js，这是一个全功能版的 Asciidoctor，可以运行在任意的 JavaScript 环境中，比如 Web 浏览器 或 Node.js。 Asciidoctor.js 被用于 AsciiDoc 预览，支持 Chrome 扩展，Atom，Brackets 或其他基于 Web 的工具。
Asciidoctor 以纯文本格式读取内容，见下图左边的面板，将它转换成 HTML5 呈现在右侧面板中。 Asciidoctor 将默认的样式表应用到 HTML5 文档上，提供一个愉快的开箱即用的体验。
Asciidoctor 读取并处理以 AsciiDoc 语法写作的文件，然后然后将解析出来的解析树交给内置的转化器生成 HTML5，DocBook 5 (或 4.5) 或帮助手册页面输出。 你可以选择使用你自己的转化器或者加载 Tilt - 支持通过模板来自定义输出或产生附加的格式。
|
Note
|
Asciidoctor是为了直接替换原 AsciiDoc Python 处理器（asciidoc.py）。
Asciidoctor 测试套件含有 > 1,600 测试用例 来确保和 AsciiDoc 语法的兼容性。
|
除了经典的 AsciiDoc 语法，Asciidoctor 还添加额外的标记和格式设置选项，例如 font-based 图标（例如： icon:fire[]）和 UI 元素（例如： button:[Save]）。
Asciidoctor 还提供了一个基于 Foundation 的现代的、响应式主题来美化 HTML5 输出。
Asciidoctor 可以在 Linux，OSX (Mac) 和 Windows，并且需要下面其中一个 Ruby 实现：
-
MRI (Ruby 1.8.7, 1.9.3, 2.0, 2.1, 2.2 & 2.3)
-
JRuby (1.7 in Ruby 1.8 and 1.9 modes, 9000)
-
Rubinius 2.2.x
-
Opal (JavaScript)
我们欢迎你来帮助在这些以及其他平台测试 Asciidoctor。 参考 Contributing 来学习如何参与进来。
|
Caution
|
如果你使用一个非英语的 Windows 环境，当调用 Asciidoctor 时，可能会碰到 chcp 65001 一旦你做了这个改变，所有的编码问题，都将迎刃而解。 只要你在任何地方都是 UTF-8，Asciidoctor 总会工作地很好。 |
Asciidoctor 可以通过三种方式安装：（a） 使用 gem install 命令；（b） 使用 Bundler；（c） 流行的 Linux 发行版的包管理器
|
Tip
|
使用 Linux 包管理器安装的好处是如果 Ruby 和 RubyGems 库没有在你的机器上安装，它会一并安装上去。
不利的是在 gem 发布之后，这类安装包并不是立即可用。
如果你需要最新版，你应该总是优先使用 gem 命令安装。
|
打开一个终端输入如下命令（不含开头的 $）：
$ gem install asciidoctor
如果想安装一个预览版（比如：候选发布版），请使用：
$ gem install asciidoctor --pre
|
Tip
|
升级
如果你安装有一个旧版本的 Asciidoctor，你可以使用下面的命令来升级： $ gem update asciidoctor 如果使用 $ gem cleanup asciidoctor |
-
在项目的根目录（或者当前路径），创建一个
Gemfile文件； -
在这个文件中添加
asciidoctorgem 如下：source 'https://rubygems.org' gem 'asciidoctor' # 或者明确指明版本 # gem 'asciidoctor', '1.5.4'
-
保存
Gemfile文件 -
打开终端，使用如下命令安装 gem：
$ bundle
要升级 gem 的话，在 Gemfile 文件中，指明新版本，然后再次运行 bundle 即可。
不推荐 直接使用 bundle update 命令，因为它还会升级其他 gem，也许会造成不可预料的结果。
在 Fedora 21 或更高版本中安装这个 gem，可以使用 dnf。打开终端并输入如下命令：
$ sudo dnf install -y asciidoctor
升级则使用：
$ sudo dnf update -y asciidoctor
|
Tip
|
如果你的 Fedora 系统配置的是自动升级包，在这种情况下，不需要你亲自动手升级。 |
在 Debian，Ubuntu 或 Mint 中安装这个 gem，请打开终端并输入如下命令：
$ sudo apt-get install -y asciidoctor
升级则使用：
$ sudo apt-get upgrade -y asciidoctor
|
Tip
|
如果你的 Debian 或 Ubuntu 系统配置的是自动升级包，在这种情况下，不需要你亲自动手升级。 |
使用包管理器（ apt-get ）安装的 Asciidoctor 的版本也许不是最新发布版。 请查看发行版的包库，来确定每个发行版是打包的哪个版本。
|
Caution
|
我们建议不要使用 如果你想使用一个比包管理器安装的更新版本的 Asciidoctor，你应该使用 RVM 在你的用户家目录（比如：用户空间）下安装 Ruby。
然后，你就可以放心地使用 |
如果成功安装 Asciidoctor，则在可执行程序路径中，asciidoctor 就可用了。
为了验证它的可用性，你可以在终端中执行如下命令：
$ asciidoctor --version
你应该看到关于 Asciidoctor 和 Ruby 环境信息将打印到你的终端上。
Asciidoctor 1.5.4 [http://asciidoctor.org] Runtime Environment (ruby 2.2.2p95 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
Asciidoctor 还提供了一套 API。 这套 API 是为了整合其他的 Ruby 软件，例如 Rails、Sinatra、Github，甚至其他语言，比如 Java （通过 AsciidoctorJ） 和 JavaScript （通过 Asciidoctor.js）。
asciidoctor 命令可以让你通过命令行（比如：终端）来调用 Asciidoctor。
下面的命令将 README.adoc 文件转化为 HTML，并且保存到同一目录下的 README.html 文件中。
生成的 HTML 文件名源自源文件名，只是将其扩展名改为了 .html。
$ asciidoctor README.adoc
您可以通过添加各种标志和开关控制 Asciidoctor 处理器，通过下面的命令你可以学习它的更多用法：
$ asciidoctor --help
比如，将文件写入到不同路径里，使用如下命令：
$ asciidoctor -D output README.adoc
asciidoctor 帮助页面 提供了这个命令的完整参考。
点击下面的资源，学习更多关于 asciidoctor 命令的用法。
为了在你应用中使用 Asciidoctor，首先需要引入这个 gem：
require 'asciidoctor'然后，你可以通过下面的代码将 AsciiDoc 源文件转化成一个 HTML 文件：
Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe|
Warning
|
当你通过 API 使用 Asciidoctor 时，默认的安全模式是 :secure。
在 secure 模式下，很多核心特性将不可用，包括 include 特性。
如果你想启用这些特性，你需要明确设置安全模式为 :server （推荐）或 :safe。
|
你也可以将 AsciiDoc 字符串转化我内嵌的 HTML （为了插入到一个 HTML 页面），用法如下：
content = '_Zen_ in the art of writing http://asciidoctor.org[AsciiDoc].'
Asciidoctor.convert content, safe: :safe如果你想得到完整的 HTML 文档，只需要启用 header_footer 选项即可。如下：
content = '_Zen_ in the art of writing http://asciidoctor.org[AsciiDoc].'
html = Asciidoctor.convert content, header_footer: true, safe: :safe如果你想访问已经处理过的文档，可以将转化过程拆分成离散的几步：
content = '_Zen_ in the art of writing http://asciidoctor.org[AsciiDoc].'
document = Asciidoctor.load content, header_footer: true, safe: :safe
puts document.doctitle
html = document.convert请注意：如果你不喜欢 Asciidoctor 输出结果，你完全可以改变它。 Asciidoctor 支持自定义转化器，它可以操作从待处理文件到生成文档整个环节。
一个简单的、细微地自定义输出的方式是使用模板转化器。 模板转化器运行你提供一个 Tilt 模板，这样通过模板文件来操作转化出的文档的每个节点。
这样，你就 可以 百分之百地控制你的输出。 关于更多关于 API 或自定义输出信息，请参考 用户帮助手册。
开发 Asciidoctor 项目是未来了帮助你更容易地书写和发布你的内容。 但是，如果没有反馈，我们将寸步难行。 我们鼓励你在讨论组、Twitter或聊天室里，提问为题，讨论项目的方方面面，
- 讨论组 (Nabble)
-
#asciidoctor 井号或 @asciidoctor 提醒
- 聊天 (Gitter)
-
Further information and documentation about Asciidoctor can be found on the project’s website.
Asciidoctor 组织在 Github 托管代码、议案跟踪和相关子项目。
- 代码库 (git)
- 议案跟踪
-
https://github.com/asciidoctor/asciidoctor/issues
- 在 GitHub 的 Asciidoctor 组织
Copyright © 2012-2016 Dan Allen, Ryan Waldron and the Asciidoctor Project. 这个软件的免费使用是在MIT许可条款授予的。
请看 版权声明 文件来获取更多详细信息。
Asciidoctor 由 Dan Allen 和 Sarah White 领导，并从 Asciidoctor 社区的 很多其他独立开发者 上收到了很多贡献。 项目最初由 Ryan Waldron 于 2012年基于 Nick Hengeveld 的 原型 创建。
AsciiDoc 由 Stuart Rackham 启动，并从 AsciiDoc 社区的其他独立开发者上收到很多贡献。
请看 CHANGELOG。