path: root/README-zh_CN.adoc

= Asciidoctor
Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
// settings:
: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::[]
// Variables:
:release-version: 2.0.22
// URLs:
: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
// images:
:image-url-screenshot: https://cdn.jsdelivr.net/gh/asciidoctor/asciidoctor/screenshot.png

{url-project}/[Asciidoctor] 是一个 _快速_ 的文本处理器和发布工具链，它可以将 {url-what-is-asciidoc}[AsciiDoc] 文档转化成 HTML 5、手册、PDF、EPUB 3 和其他格式。

Asciidoctor 还拥有一个由扩展、转换器、构建插件和工具组成的生态系统，可帮助你使用 {url-what-is-asciidoc}[AsciiDoc] 编写和发布文档。

你可以在 {url-docs} 找到这些项目的文档。

使用 {url-asciidoctorj}[AsciidoctorJ] 直接调用 Asciidoctor 的 API 运行在 Java 或者其他基于 Java 语言的虚拟机中。
使用 {url-asciidoctorjs}[Asciidoctor.js] 运行在 JavaScript 当中。

ifndef::env-site,env-yard[]
该文档有如下语言的翻译版：

* {url-rel-file-base}README.adoc[English]
* {url-rel-file-base}README-fr.adoc[Français]
* {url-rel-file-base}README-jp.adoc[日本語]
* {url-rel-file-base}README-de.adoc[Deutsch]
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[Latest Release, link={url-rubygem}]
image:https://img.shields.io/badge/rubydoc.info-{release-version}-blue.svg[library (API) docs,link=https://www.rubydoc.info/gems/asciidoctor/{release-version}]
image:https://github.com/asciidoctor/asciidoctor/workflows/CI/badge.svg[Build Status (GitHub Actions),link={url-repo}/actions]
image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg[Project Chat (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}[Preview of AsciiDoc source and corresponding rendered 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/[手册]。
额外的转换器，如 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。
你可以使用 {url-asciidoctorj}[AsciidoctorJ] 直接调用 Asciidoctor 的 API 运行在 Java 或者其他基于 Java 语言的虚拟机中。
你可以使用 {url-asciidoctorjs}[Asciidoctor.js] 运行在 JavaScript 当中。

安装 Asciidoctor 处理器只是文档处理体验的开始。
Asciidoctor 使你可以使用扩展和工具的生态系统，从附加的转换器到扩展语法、构建插件，再到集成的写入和预览环境，都有相应的支持：

* {url-docs}/diagram-extension/latest/[Asciidoctor 图表]
* {url-docs}/maven-tools/latest/[Maven 插件 and site 模块]
* {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[web 浏览器扩展]
* {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.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）的形式打包和分发，被命名为 {url-rubygem}[asciidoctor^]。
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 的发行版上安装, 打开终端并键入：

 $ sudo pacman -S asciidoctor

==== APT

在 Ubuntu 等基于 Debian 和 Debian 的发行版上，使用 APT 安装 Asciidoctor。
要安装，打开终端并键入：

 $ sudo apt-get install -y asciidoctor

==== DNF

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

 $ sudo dnf install -y asciidoctor

=== macOS

==== Homebrew

你可以使用 https://brew.sh[Homebrew]，macOS 包管理器，去安装 Asciidoctor。
如果你的电脑上没有 Homebrew，先 https://brew.sh[安装] 它。

Homebrew 安装好以后，你就可以安装 `asciidoctor` gem 了。
打开终端并键入：

 $ brew install asciidoctor

Homebrew 安装 `asciidoctor` gem 到一个独有的“前缀”中，它独立于系统的 gem。

==== MacPorts

你也可以使用 https://www.macports.org[MacPorts]，macOS 的包管理器，用于安装 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]，下载它，然后参照 <<gem-install,gem 安装说明>>。

[#gem-install]
=== gem install

在你使用 `gem install` 安装 AsciiDoctor 之前，你应该安装 https://rvm.io[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

=== Docker

参见 {url-install-docker}[使用 Docker 安装 Asciidoctor]。

=== Bundler

. 在项目的根目录（或当前目录）中创建一个 Gemfile
. 将 `asciidoctor` gem 像下面这样加入到 Gemfile 中：
+
[subs=attributes+]
----
source 'https://rubygems.org'
gem 'asciidoctor'
# or specify the version explicitly
# gem 'asciidoctor', '{release-version}'
----

. 保存 Gemfile
. 打开命令行安装 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 install asciidoctor

当你使用 `gem install` 安装 gem 的新版本时，你最终会安装多个版本。
使用下面的命令来移除旧版本：

 $ gem cleanup asciidoctor

== 使用

如果成功安装 Asciidoctor gem，`Asciidoctor` 命令行界面（CLI）将可用。
要验证它是否可用，在终端中运行以下命令:

 $ asciidoctor --version

你应该在终端中可以看到关于 Asciidoctor 版本和 Ruby 环境的信息。

[.output,subs=attributes+]
....
Asciidoctor {release-version} [https://asciidoctor.org]
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。然后将结果保存到同一目录下的文件 README.html 中。
通过将源文件的扩展名更改为 `.html`，生成的HTML文件的名称派生自源文件。

 $ asciidoctor README.adoc

你可以通过添加各种标志和开关来控制 Asciidoctor 处理器，你可以学习如何使用这些标志和开关：

 $ asciidoctor --help

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

 $ asciidoctor -D output README.adoc

`asciidoctor` {url-manpage}[帮助手册] 提供了 CLI 的完整参考文档。

参考下面的参考资料，了解如何使用 `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
----

WARNING: 当通过 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/[安全模式]

== 贡献

我们欢迎贡献者！
如果你在源代码、文档或网站内容中发现错误或遗漏，请不要犹豫，提交一个 issue 或 Pull Request。

这里有一些 *你* 可以参与贡献的方式：

* 使用预发行版（alpha, beta或preview）
* 报告漏洞
* 提出新特性
* 撰写或编辑文档
* 测试和代码—— _没有什么补丁是微不足道的。_
** 修复排版错误
** 添加补丁
** 清理不一致的空白字符
** 撰写测试
* 重构代码
* 修复 {url-issues}[issue]
* 审查补丁

{url-contribute}[贡献指南] 提供了关于如何创建、排版和提交 issue、特性请求、代码和文档到 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 组织托管着项目的源代码、issue tracker 和子项目。

源代码仓库（Git）:: {url-repo}
Issue tracker:: {url-issues}
GitHub 上的 AsciiDoctor 组织:: {url-org}

== 行为准则

Asciidoctor 的核心项目是由 https://github.com/asciidoctor/.github/blob/HEAD/CODE-OF-CONDUCT.md[行为准则] 管理的 Asciidoctor 项目社区。参与就代表你就同意遵守这个准则。让我们一起努力，为每个人创造一个受欢迎、专业、包容和安全的环境。

== 版本控制和发布策略

这个项目遵循语义化版本控制 （*主版本号.次版本号.修订号*）。
通常，补丁版本只针对当前的次要版本。
但是，为了解决安全漏洞和其他高优先级问题，会根据具体情况制定例外情况。

== 版权和许可证

Copyright (C) 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.

参见 {url-license}[LICENSE] 以获取完整的许可证信息。

== 作者

*Asciidoctor* 由 https://github.com/mojavelinux[Dan Allen] 和 https://github.com/graphitefriction[Sarah White] 发起，已经有 {url-contributors}[很多人] 在 Asciidoctor 很棒的社区里为项目作出贡献。该项目于 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) and AsciiDoc Language(TM) are trademarks of the Eclipse Foundation, Inc.

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

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

参见 {url-changelog}[更新日志] 查看完整的日志列表。
endif::[]