= Asciidoctor Dan Allen https://github.com/mojavelinux[@mojavelinux]; Sarah White https://github.com/graphitefriction[@graphitefriction] // 设置: :idprefix: :idseparator: - :source-language: ruby ifndef::env-github[:icons: font] ifdef::env-github[] :status: :caution-caption: :fire: :important-caption: :exclamation: :note-caption: :paperclip: :tip-caption: :bulb: :warning-caption: :warning: endif::[] // 变量: :release-version: 2.0.22 // URL: :url-org: https://github.com/asciidoctor :url-repo: {url-org}/asciidoctor :url-asciidoctorj: {url-org}/asciidoctorj :url-asciidoctorjs: {url-org}/asciidoctor.js :url-gradle-plugin: {url-org}/asciidoctor-gradle-plugin :url-maven-plugin: {url-org}/asciidoctor-maven-plugin :url-asciidoclet: {url-org}/asciidoclet :url-project: https://asciidoctor.org ifdef::env-site[:url-project: link:] :url-docs: https://docs.asciidoctor.org :url-news: {url-project}/news :url-manpage: {url-project}/man/asciidoctor :url-issues: {url-repo}/issues :url-contributors: {url-repo}/graphs/contributors :url-rel-file-base: link: :url-rel-tree-base: link: ifdef::env-site,env-yard[] :url-rel-file-base: {url-repo}/blob/HEAD/ :url-rel-tree-base: {url-repo}/tree/HEAD/ endif::[] :url-changelog: {url-rel-file-base}CHANGELOG.adoc :url-contribute: {url-rel-file-base}CONTRIBUTING.adoc :url-license: {url-rel-file-base}LICENSE :url-tests: {url-rel-tree-base}test :url-discuss: https://discuss.asciidoctor.org :url-chat: https://chat.asciidoctor.org :url-rubygem: https://rubygems.org/gems/asciidoctor :url-what-is-asciidoc: {url-docs}/asciidoctor/latest/#relationship-to-asciidoc :url-install-docker: https://github.com/asciidoctor/docker-asciidoctor :url-opal: https://opalrb.com :url-tilt: https://github.com/rtomayko/tilt :url-ruby: https://www.ruby-lang.org // 图片: :image-url-screenshot: https://cdn.jsdelivr.net/gh/asciidoctor/asciidoctor/screenshot.png

{url-project}[Asciidoctor]是一个快速、开源的基于Ruby的文本处理器,用于将AsciiDoc(R)解析为文档模型并将其转换为HTML 5、DocBook 5、手册页、PDF、EPUB 3等输出格式。

Asciidoctor还拥有扩展、转换器、构建插件和工具的生态系统,可帮助您创作和发布用{url-what-is-asciidoc}[AsciiDoc]编写的内容。您可以在{url-docs}找到这些项目的文档。

除了在Ruby上运行外,Asciidoctor还可以使用{url-asciidoctorj}[AsciidoctorJ]在JVM上执行,或使用{url-asciidoctorjs}[Asciidoctor.js]在任何JavaScript环境中执行。

ifndef::env-site,env-yard[] 本文档还提供以下语言版本: + {url-rel-file-base}README-zh_CN.adoc[简体中文] | {url-rel-file-base}README-de.adoc[Deutsch] | {url-rel-file-base}README-fr.adoc[Français] | {url-rel-file-base}README-jp.adoc[日本語] endif::[]

.主要文档 [.compact]

{url-docs}/asciidoctor/latest/[Asciidoctor文档]
{url-docs}/asciidoc/latest/[AsciiDoc语言文档]
{url-docs}/asciidoc/latest/syntax-quick-reference/[AsciiDoc语法快速参考]

ifdef::status[] image:https://img.shields.io/gem/v/asciidoctor.svg[最新版本, link={url-rubygem}] image:https://img.shields.io/badge/rubydoc.info-{release-version}-blue.svg[库(API)文档,link=https://www.rubydoc.info/gems/asciidoctor/{release-version}] image:https://github.com/asciidoctor/asciidoctor/workflows/CI/badge.svg[构建状态(GitHub Actions),link={url-repo}/actions] image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg[项目聊天(Zulip),link={url-chat}] endif::[]

== 赞助商

我们想要感谢我们的{url-project}/supporters[赞助商]对改善技术文档状况的承诺,感谢他们对本项目的支持。感谢赞助商! 没有你们的慷慨支持,Asciidoctor将无法实现。

你可以通过https://opencollective.com/asciidoctor[OpenCollective]成为赞助商来支持这个项目。

== AsciiDoc处理和内置转换器

AsciiDoc是语言。+ Asciidoctor是处理器。

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

image::{image-url-screenshot}[AsciiDoc源文件和相应渲染的HTML预览]

Asciidoctor默认为三种输出格式提供内置的{url-docs}/asciidoctor/latest/converters/[转换器]:{url-docs}/asciidoctor/latest/html-backend/[HTML 5]、{url-docs}/asciidoctor/latest/docbook-backend/[DocBook 5]和{url-docs}/asciidoctor/latest/manpage-backend/man page。其他转换器(如PDF和EPUB 3)由单独的gem提供。 Asciidoctor还提供了开箱即用的HTML体验,包括{url-docs}/asciidoctor/latest/html-backend/default-stylesheet/[默认样式表]和内置集成,如Font Awesome(用于图标)、highlight.js、Rouge和Pygments(用于源代码高亮)以及MathJax(用于STEM处理)。

== Asciidoctor生态系统

虽然Asciidoctor是用Ruby编写的,但这并不意味着您需要Ruby才能使用它。 Asciidoctor可以使用{url-docs}/asciidoctorj/latest/[AsciidoctorJ]在JVM上执行,或使用{url-docs}/asciidoctor.js/latest/[Asciidoctor.js]在任何JavaScript环境(包括浏览器)中执行。

安装Asciidoctor处理器只是您发布体验的开始。 Asciidoctor为您提供了一个扩展和工具的生态系统,包括附加转换器、扩展语法、构建插件以及集成的写作和预览环境:

{url-docs}/diagram-extension/latest/[Asciidoctor Diagram]
{url-docs}/maven-tools/latest/[Maven插件和站点模块]
{url-gradle-plugin}[Gradle插件]
{url-docs}/asciidoclet/latest/[Asciidoclet]
{url-docs}/reveal.js-converter/latest/[reveal.js转换器]
{url-docs}/epub3-converter/latest/[EPUB 3转换器]
https://intellij-asciidoc-plugin.ahus1.de/docs[IntelliJ插件]
{url-docs}/asciidoctor/latest/tooling/#web-browser-add-ons-preview-only[网页浏览器扩展]
{url-org}[以及更多]

Asciidoctor是AsciiDoc.py的继任者。如果您正在使用AsciiDoc.py,请参阅{url-docs}/asciidoctor/latest/migrate/asciidoc-py/[从AsciiDoc.py迁移]了解如何升级到Asciidoctor。

== 要求

Asciidoctor可在Linux、macOS和Windows上运行,并要求使用以下{url-ruby}[Ruby]实现之一:

CRuby(又称MRI) 2.7 - 3.3
JRuby 9.2 - 9.4
TruffleRuby (GraalVM)

[CAUTION]

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

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

进行此更改后,所有Unicode相关的问题应该都解决了。

如果您使用的是Eclipse等IDE,请确保也将其中的编码设置为UTF-8。 Asciidoctor经过优化,可以使用UTF-8作为默认编码。

== 安装

Asciidoctor作为名为{url-rubygem}[asciidoctor^]的RubyGem(又称gem)打包并分发到RubyGems.org。 asciidoctor gem可以使用Ruby打包工具(gem或bundle)在所有主要操作系统上安装。 Asciidoctor还以Docker镜像、众多Linux发行版的软件包以及macOS软件包(通过Homebrew和MacPorts)的形式分发。

=== Linux包管理器

包管理器安装的Asciidoctor版本可能与Asciidoctor的最新发布版本不匹配。请查阅您的发行版的软件包仓库,了解每个发行版打包的版本。

https://pkgs.alpinelinux.org/packages?name=asciidoctor[Alpine Linux (asciidoctor)]
https://www.archlinux.org/packages/?name=asciidoctor[Arch Linux (asciidoctor)]
https://packages.debian.org/sid/asciidoctor[Debian (asciidoctor)]
https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Fedora (asciidoctor)]
https://software.opensuse.org/package/rubygem-asciidoctor[OpenSUSE (rubygem-asciidoctor)]
https://packages.ubuntu.com/search?keywords=asciidoctor[Ubuntu (asciidoctor)]

如果您想使用比包管理器安装的版本更新的Asciidoctor版本,请参阅<<gem-install,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包管理器https://brew.sh[Homebrew]安装Asciidoctor。如果您的计算机上没有Homebrew,请先完成https://brew.sh[安装说明]。

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

$ brew install asciidoctor

Homebrew将asciidoctor gem安装到独立于系统gem的专用前缀中。

==== MacPorts

您还可以使用macOS的另一个包管理器https://www.macports.org[MacPorts]安装Asciidoctor。如果您的计算机上没有MacPorts,请先完成https://www.macports.org/install.php[安装说明]。

安装MacPorts后,您就可以通过https://ports.macports.org/port/asciidoctor/[Asciidoctor port]安装asciidoctor gem了。打开终端并输入:

$ sudo port install asciidoctor

=== Windows

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

==== Chocolatey

如果您的机器上已经使用https://chocolatey.org[chocolatey],可以使用:

choco install ruby

然后按照<<gem-install,gem安装说明>>进行操作。

==== Rubyinstaller

或者您可以使用https://rubyinstaller.org/downloads/[Rubyinstaller],下载适合您Windows版本的软件包,安装后按照<<gem-install,gem安装说明>>进行操作。

[#gem-install] === gem install

使用gem install安装Asciidoctor之前,您应该设置https://rvm.io[RVM](或类似工具)以在您的主目录(即用户空间)中安装Ruby。然后,您可以安全地使用gem命令来安装或更新Asciidoctor gem,或任何其他gem。使用RVM时,gem安装在与系统隔离的位置。 (您永远不应该使用gem命令来安装系统范围的gem)。

使用RVM安装Ruby并使用rvm use 3.0激活它后,打开终端并输入:

$ gem install asciidoctor

如果您想安装预发布版本(例 $ asciidoctor -D output README.adoc

asciidoctor {url-manpage}[手册页]提供了命令行界面的完整参考。

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

{url-docs}/asciidoctor/latest/cli/[使用 CLI 处理 AsciiDoc]
{url-docs}/asciidoctor/latest/cli/options/[CLI 选项]

=== Ruby API

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 支持自定义转换器，可以处理从解析文档到生成输出的转换。

一种简单的方法是使用模板转换器来逐步自定义输出。模板转换器允许您提供一个 {url-tilt}[Tilt] 支持的模板文件来处理文档中任何节点的转换。

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

{url-docs}/asciidoctor/latest/api/[使用 API 处理 AsciiDoc]
{url-docs}/asciidoctor/latest/api/options/[API 选项]
{url-docs}/asciidoctor/latest/safe-modes/[安全模式]

== 贡献

我们始终欢迎新的贡献者！如果您在源代码、文档或网站内容中发现错误或遗漏，请不要犹豫，提交一个问题或打开一个带有修复的拉取请求。

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

使用预发布版本（alpha、beta 或预览版）
报告错误
提出新功能建议
编写或编辑文档
编写带有测试的代码 -- 没有补丁太小。 ** 修复拼写错误 ** 添加注释 ** 清理不一致的空白 ** 编写测试！
重构代码
修复 {url-issues}[问题]
审查补丁

{url-contribute}[贡献] 指南提供了有关如何创建、样式化和提交问题、功能请求、代码和文档到 Asciidoctor 的信息。

== 获取帮助

Asciidoctor 的开发旨在帮助您轻松编写和发布您的内容。但没有您的输入，我们无法做到这一点。如果您需要帮助或想提供反馈，请按照文档中 https://docs.asciidoctor.org/about/support/[获取帮助] 页面上列出的资源链接。以下是一个快速摘要：

项目聊天（Zulip）:: {url-chat} 讨论列表（存档）:: {url-discuss} 社交媒体（Twitter）:: 关注 https://twitter.com/asciidoctor[@asciidoctor] 或搜索 https://twitter.com/search?f=tweets&q=%23asciidoctor[#asciidoctor] 标签

ifdef::env-github[] 关于 Asciidoctor 的更多信息和文档可以在项目网站上找到。

{url-project}[首页] | {url-news}[新闻] | {url-docs}[文档] endif::[]

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

源代码仓库（git）:: {url-repo} 问题跟踪器:: {url-issues} GitHub 上的 Asciidoctor 组织:: {url-org}

== 行为准则

Asciidoctor 核心项目受 Asciidoctor 项目社区的 https://github.com/asciidoctor/.github/blob/HEAD/CODE-OF-CONDUCT.md[行为准则] 管理。通过参与，您同意遵守此准则。让我们共同努力，使这成为一个欢迎、专业、包容和安全的环境。

== 版本控制和发布政策

本项目遵循语义版本控制（主版本号.次版本号.修订号）。通常，修订版本只针对当前的次要版本发布。然而，在处理安全漏洞和其他高优先级问题时，会根据具体情况做出例外。

== 版权和许可

完整的许可证文本请参见 {url-license}[LICENSE]。

== 作者

Asciidoctor 由 https://github.com/mojavelinux[Dan Allen] 和 https://github.com/graphitefriction[Sarah White] 领导，并得到了 Asciidoctor 优秀社区中 {url-contributors}[许多个人] 的贡献。该项目于 2012 年由 https://github.com/erebor[Ryan Waldron] 发起，基于 https://github.com/nickh[Nick Hengeveld] 为 Git 网站编写的原型。

AsciiDoc.py 由 Stuart Rackham 从 https://github.com/asciidoc-py/asciidoc-py2/blob/HEAD/CHANGELOG.txt[2002 年到 2013 年] 开始并维护，并得到了 https://github.com/asciidoc-py/asciidoc-py2/graphs/contributors[AsciiDoc.py 社区] 中许多个人的贡献。

== 商标

AsciiDoc(R) 和 AsciiDoc Language(TM) 是 Eclipse Foundation, Inc. 的商标。

ifndef::env-site[] == 更新日志

ifeval::[{safe-mode-level} < 20] include::CHANGELOG.adoc[tag=compact,leveloffset=+1] endif::[]

有关旧版本中完整的更改列表，请参阅 {url-changelog}[CHANGELOG]。 endif::[]