Asciidoctor是一个快速、开源的文本处理器和发布工具链，用于将AsciiDoc内容转换为HTML5、DocBook、PDF和其他格式。Asciidoctor是用Ruby编写的，可在所有主要操作系统上运行。Asciidoctor项目托管在GitHub上。
为了简化安装，Asciidoctor被打包并作为RubyGems.org的RubyGem(又名gem)分发给RubyGems.org。它还作为流行的Linux发行版和MacOS的软件包分发。除了在Ruby上运行之外，Asciidoctor还可以使用AsciidoctorJ在JVM上执行，或者使用Asciidoctor.js在任何JavaScript环境(包括浏览器)中执行。
我们想表彰我们的赞助商通过支持这个项目来改善技术文档状况的承诺。谢谢赞助商！没有你们的慷慨支持，Asciidoctor就不可能实现。
Asciidoctor读取以纯文本编写的内容，如下图左侧面板所示，并将其转换为HTML5，如右侧面板所示。Asciidoctor将默认样式表应用于HTML5文档，以提供愉快的开箱即用体验。
Asciidoctor读取并解析以AsciiDoc语法编写的文本，然后将解析树提供给一组内置转换器以生成HTML5、DocBook 5和手册页输出。您可以选择使用自己的转换器或加载支持倾斜的模板来自定义生成的输出或生成其他格式。
Asciidoctor是其前身AsciiDoc Python(asciidoc.py)的临时替代品。Asciidoctor测试套件有2350个测试，以确保与AsciiDoc语法兼容。
除了经典的AsciiDoc语法之外，Asciidoctor还识别其他标记和格式选项，例如基于字体的图标(例如，icon：fire[])和UI元素(例如，button：[save])。Asciidoctor还提供了基于Foundation的现代、响应迅速的主题，以设置HTML5输出的样式。
您可以使用JRuby在JVM上运行Asciidoctor。要直接从Java和其他JVM语言调用Asciidoctor API，请使用AsciidoctorJ。Apache Maven、Gradle和Javadoc都有可用的插件，这些插件允许您使用AsciidoctorJ将AsciiDoc处理直接集成到您的构建中。
Asciidoctor也可以在JavaScript中运行。Opal用于将Ruby源代码转换为JavaScript以生成Asciidoctor.js。Asciidoctor.js是一个全功能版本的Asciidoctor，可以在任何JavaScript环境下工作，例如Web浏览器或Node.js。它用于支持Chrome、Atom、支架和其他基于Web的工具的AsciiDoc预览扩展。
Asciidoctor可以在Linux、MacOS和Windows上运行，并且需要以下Ruby实现之一：
如果您使用的是非英语Windows环境，则在调用Asciidoctor时可能会遇到Encoding：：UnfinedConversionError。要解决此问题，我们建议将控制台中的活动代码页更改为UTF-8：
一旦您进行了此更改，所有的Unicode难题都将不复存在。如果您使用的是Eclipse之类的IDE，请确保在那里也将编码设置为UTF-8。当您在任何地方使用UTF-8时，Asciidoctor都能工作得最好。
可以使用(A)适用于流行Linux发行版的软件包管理器、(B)适用于MacOS的Homebrew、(C)gem install命令(建议Windows用户使用)、(D)Asciidoctor Docker映像或(E)捆绑程序来安装Asciidoctor。
使用操作系统的包管理器安装gem的好处是，如果您的计算机上尚未安装Ruby和RubyGems库，则它可以处理这些包的安装。
软件包管理器安装的Asciidoctor版本可能与最新版本的Asciidoctor不匹配。请咨询您的发行版的软件包存储库，以了解每个发行版打包的是哪个版本。
如果您想使用比软件包管理器安装的版本更新的Asciidoctor版本，请参阅gem安装说明。
在Debian和基于Debian的发行版(如Ubuntu)上，使用apt安装Asciidoctor。要安装该软件包，请打开终端并键入：
在基于RPM的Linux发行版(如Fedora、CentOS和RHEL)上，使用DNF软件包管理器安装Asciidoctor。要安装该软件包，请打开终端并键入：
您可以使用MacOS软件包管理器HomeBREW安装Asciidoctor。如果您的计算机上没有HomeBREW，请先完成brew.sh上的安装说明。一旦安装了HomeBREW，您就可以安装asciidoctor gee了。打开终端并键入：
Homebrew将asciidoctor gem安装到独立于系统gem的独占前缀中。
或者使用RubyInstaller，下载适用于您的Windows版本的软件包，然后在安装之后继续执行gem安装说明。
在使用gem install安装Asciidoctor之前，您应该使用RVM在您的主目录(即用户空间)中安装Ruby。然后，您可以安全地使用gem命令安装或更新Asciidoctor gem。使用RVM时，gem安装在与系统隔离的位置。
要升级gem，请在Gemfile中指定新版本，然后再次运行包。不建议使用包更新(不指定gem)，因为它还会更新其他gem，这可能不是预期的结果。
如果您使用软件包管理器安装了Asciidoctor，则您的操作系统可能配置为自动更新软件包，在这种情况下，您不需要手动更新gem。
如果以前使用gem命令安装了Asciidoctor，则需要在发布新版本时手动升级Asciidoctor。您可以通过键入以下命令升级GEM：
使用gem install安装新版本的gem时，最终会安装多个版本。使用以下命令删除旧版本：
如果成功安装了Asciidoctor gem，则您的PATH上将提供asciidoctor命令行界面(CLI)。要验证它是否可用，请在您的终端中运行以下命令：
您应该会在终端中看到有关Asciidoctor版本和Ruby环境的信息。
Asciidoctor还提供API。该API旨在与其他Ruby软件集成，如Rails、Sinatra和GitHub，以及其他语言，如Java(通过AsciidoctorJ)和JavaScript(通过Asciidoctor.js)。
Asciidoctor命令允许您从命令行(即终端)调用Asciidoctor。
以下命令将文件readme.adoc转换为HTML，并将结果保存到同一目录下的文件readme.html中。生成的HTML文件的名称通过将其文件扩展名更改为.html来派生自源文件。
您可以通过添加各种标志和开关来控制Asciidoctor处理器，您可以了解如何使用这些标志和开关：
请参考以下资源了解有关如何使用asciidoctor命令的更多信息。
通过API使用Asciidoctor时，默认的安全模式为：secure。在安全模式下，将禁用几个核心功能，包括include指令。如果要启用这些功能，则需要将安全模式显式设置为：server(推荐)或：safe。
您还可以使用以下方法将AsciiDoc字符串转换为可嵌入的HTML(用于插入到HTML页面中)：
Https://asciidoctor.org[AsciiDoc].写作艺术中的Content='；_Zen_。'；html=Asciidoctor.Convert内容，Header_Footer：true，Safe：：Safe。
如果您需要访问解析的文档，可以将转换拆分成离散的步骤：
Https://asciidoctor.org[AsciiDoc].写作艺术中的Content='；_Zen_。'；document=Asciidoctor.load content，HEADER_FOOTER：TRUE，SAFE：：Safeput Docent.doctitlehtml=Docent.Convert。
请记住，如果您不喜欢Asciidoctor生成的输出，您可以更改它！Asciidoctor支持自定义转换器，可以处理从解析的文档到生成的输出的转换。
一种简单的逐段定制输出的方法是使用模板转换器，模板转换器允许您提供支持倾斜的模板文件来处理文档中任何节点的转换。
无论如何，您都可以100%控制输出。有关如何使用API或自定义输出的详细信息，请参阅用户手册。
欢迎新投稿人！如果您在源代码、文档或网站内容中发现错误或遗漏，请毫不犹豫地提交问题或打开带有修复的拉取请求。
贡献指南提供了有关如何创建问题、功能请求、代码和文档以及如何向Asciidoctor项目提交问题、功能请求、代码和文档的信息。
Asciidoctor是为了帮助您轻松编写和发布您的内容而开发的。但是，没有您的反馈，我们无法做到这一点！我们鼓励您在讨论列表、Twitter或聊天室中提出问题并讨论项目的任何方面。
GitHub上的Asciidoctor组织托管项目的源代码、问题跟踪器和子项目。
版权所有©2012-2019 Dan Allen、Sarah White、Ryan Waldron和Asciidoctor的个人贡献者。本软件的使用是根据MIT许可条款授予的。
Asciidoctor由丹·艾伦和莎拉·怀特领导，在Asciidoctor令人敬畏的社区中收到了许多个人的贡献。该项目由瑞安·沃尔德隆于2012年发起，基于尼克·亨格维尔德撰写的原型。
AsciiDoc是由Stuart Rackham创立的，已经收到了AsciiDoc社区中许多个人的贡献。