Skip to content

Latest commit

 

History

History
488 lines (335 loc) · 18.7 KB

README-zh_CN.adoc

File metadata and controls

488 lines (335 loc) · 18.7 KB

Asciidoctor

Asciidoctor 是一个 快速 的文本处理器和发布工具链,它可以将 AsciiDoc 文档转化成 HTML 5、手册、PDF、EPUB 3 和其他格式。

Asciidoctor 还拥有一个由扩展、转换器、构建插件和工具组成的生态系统,可帮助你使用 AsciiDoc 编写和发布文档。

你可以在 https://docs.asciidoctor.org 找到这些项目的文档。

使用 AsciidoctorJ 直接调用 Asciidoctor 的 API 运行在 Java 或者其他基于 Java 语言的虚拟机中。 使用 Asciidoctor.js 运行在 JavaScript 当中。

该文档有如下语言的翻译版:

Latest Release library (API) docs Build Status (GitHub Actions) Project Chat (Zulip)

赞助商

我们想感谢我们的 赞助商 致力于通过支持此项目来改善技术文档的生态。谢谢赞助商!没有你们的慷慨支持,Asciidoctor 不可能持续下去。

你可以通过 OpenCollective 成为发起人来支持此项目。

AsciiDoc 处理器和内置转换器

AsciiDoc 是语言。 Asciidoctor 是处理器。

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

Preview of AsciiDoc source and corresponding rendered HTML

Asciidoctor 提供内置的 转换器,默认三种格式: HTML 5DocBook 5手册。 额外的转换器,如 PDF 和 EPUB 3 是由单独的 gem 提供的。 Asciidoctor还提供开箱即用的 HTML 体验,并提供 默认样式 和内置集成,如 Font Awesome (为图标设计的)、highlight.js、Rouge、和 Pygments (代码高亮)、和 MathJax(STEM 处理)。

Asciidoctor 生态系统

虽然 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)。

Linux 包管理器

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

如果你想使用更高版本的 Asciidoctor,参见 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

你可以使用 Homebrew,macOS 包管理器,去安装 Asciidoctor。 如果你的电脑上没有 Homebrew,先 安装 它。

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

$ brew install asciidoctor

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

MacPorts

你也可以使用 MacPorts,macOS 的包管理器,用于安装 Asciidoctor。 如果你的计算机上没有 MacPorts,先 安装

安装 MacPorts 后,你就可以通过 Asciidoctor port 安装 asciidoctor gem 了。 打开终端并键入:

$ sudo port install asciidoctor

Windows

要在 Windows 上使用 Asciidoctor,你有两个选择:

Chocolatey

当你已经有 chocolatey 工具时,你可以使用:

choco install ruby

然后参照 gem 安装说明

Rubyinstaller

或者你可以使用 Rubyinstaller,下载它,然后参照 gem 安装说明

gem install

在你使用 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

Bundler

  1. 在项目的根目录(或当前目录)中创建一个 Gemfile

  2. asciidoctor gem 像下面这样加入到 Gemfile 中:

    source 'https://rubygems.org'
    gem 'asciidoctor'
    # or specify the version explicitly
    # gem 'asciidoctor', '2.0.20'
  3. 保存 Gemfile

  4. 打开命令行安装 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 环境的信息。

Asciidoctor 2.0.20 [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 帮助手册 提供了 CLI 的完整参考文档。

参考下面的参考资料,了解如何使用 asciidoctor 命令:

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 支持自定义转换器,可以处理从解析文档到生成输出的转换。 定制输出片段的一种简单方法是使用模板转换器。 模板转换器允许你提供一个 Tilt——以支持使用模板文件来处理转换文档中的任何节点。

不管你怎么做,你都可以 100% 控制输出。 有关如何使用 API 或定制输出的更多信息,请参见:

贡献

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

这里有一些 可以参与贡献的方式:

  • 使用预发行版(alpha, beta或preview)

  • 报告漏洞

  • 提出新特性

  • 撰写或编辑文档

  • 测试和代码—— 没有什么补丁是微不足道的。

    • 修复排版错误

    • 添加补丁

    • 清理不一致的空白字符

    • 撰写测试

  • 重构代码

  • 修复 issue

  • 审查补丁

贡献指南 提供了关于如何创建、排版和提交 issue、特性请求、代码和文档到 Asciidoctor 的信息。

获取帮助

Asciidoctor 旨在帮助你轻松编写和发布内容。 但没有你的参与,我们做不到! 如果你需要帮助或希望提供反馈,请点击 获取帮助 中所列举的一些资源,这里有一个小结供你参考:

聊天室(Zulip)

https://chat.asciidoctor.org

讨论列表(只读,已归档)

https://discuss.asciidoctor.org

社交媒体(Twitter)

关注 @asciidoctor 或者搜索 #asciidoctor 标签

关于 Asciidoctor 的更多信息和文档可以在该项目的网站上找到。

GitHub 上的 Asciidoctor 组织托管着项目的源代码、issue tracker 和子项目。

行为准则

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 以获取完整的许可证信息。

作者

AsciidoctorDan AllenSarah White 发起,已经有 很多人 在 Asciidoctor 很棒的社区里为项目作出贡献。该项目于 2012 年由 Ryan Waldron 发起,基于 Nick Hengeveld 为 Git 网站编写的原型。AsciiDoc.py 由 Stuart Rackham 自 2002 年到 2013 年 发起并维护。有很多来自 AsciiDoc.py 社区 的人们为项目作出贡献。

商标

AsciiDoc® and AsciiDoc Language™ are trademarks of the Eclipse Foundation, Inc.

更新日志

参见 更新日志 查看完整的日志列表。