asciidoctor 1.5.6.2 → 1.5.7

data/README-zh_CN.adoc

@@ -0,0 +1,430 @@
+= Asciidoctor
+Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Ryan Waldron <https://github.com/erebor[@erebor]>
+v1.5.7, 2018-05-02
+// settings:
+:page-layout: base
+:idprefix:
+:idseparator: -
+:source-language: ruby
+:language: {source-language}
+ifndef::env-github[:icons: font]
+ifdef::env-github[]
+:status:
+:outfilesuffix: .adoc
+:caution-caption: :fire:
+:important-caption: :exclamation:
+:note-caption: :paperclip:
+:tip-caption: :bulb:
+:warning-caption: :warning:
+endif::[]
+// Variables:
+:release-version: 1.5.7
+// URIs:
+:uri-org: https://github.com/asciidoctor
+:uri-repo: {uri-org}/asciidoctor
+:uri-asciidoctorj: {uri-org}/asciidoctorj
+:uri-asciidoctorjs: {uri-org}/asciidoctor.js
+:uri-project: http://asciidoctor.org
+ifdef::env-site[:uri-project: link:]
+:uri-docs: {uri-project}/docs
+:uri-news: {uri-project}/news
+:uri-manpage: {uri-project}/man/asciidoctor
+:uri-issues: {uri-repo}/issues
+:uri-contributors: {uri-repo}/graphs/contributors
+:uri-rel-file-base: link:
+:uri-rel-tree-base: link:
+ifdef::env-site[]
+:uri-rel-file-base: {uri-repo}/blob/master/
+:uri-rel-tree-base: {uri-repo}/tree/master/
+endif::[]
+:uri-changelog: {uri-rel-file-base}CHANGELOG.adoc
+:uri-contribute: {uri-rel-file-base}CONTRIBUTING.adoc
+:uri-license: {uri-rel-file-base}LICENSE
+:uri-tests: {uri-rel-tree-base}test
+:uri-discuss: http://discuss.asciidoctor.org
+:uri-irc: irc://irc.freenode.org/#asciidoctor
+:uri-rubygem: https://rubygems.org/gems/asciidoctor
+:uri-what-is-asciidoc: {uri-docs}/what-is-asciidoc
+:uri-user-manual: {uri-docs}/user-manual
+:uri-install-docker: https://github.com/asciidoctor/docker-asciidoctor
+//:uri-install-doc: {uri-docs}/install-toolchain
+:uri-install-osx-doc: {uri-docs}/install-asciidoctor-macosx
+:uri-render-doc: {uri-docs}/render-documents
+:uri-themes-doc: {uri-docs}/produce-custom-themes-using-asciidoctor-stylesheet-factory
+:uri-gitscm-repo: https://github.com/git/git-scm.com
+:uri-prototype: {uri-gitscm-repo}/commits/master/lib/asciidoc.rb
+:uri-freesoftware: https://www.gnu.org/philosophy/free-sw.html
+:uri-foundation: http://foundation.zurb.com
+:uri-tilt: https://github.com/rtomayko/tilt
+:uri-ruby: https://ruby-lang.org
+// images:
+:image-uri-screenshot: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/screenshot.png
+
+{uri-project}/[Asciidoctor] 是一个 _快速_ 文本处理器和发布工具链，它可以将 {uri-what-is-asciidoc}[AsciiDoc] 文档转化成 HTML5、 DocBook 5 (或 4.5) 以及其他格式。
+Asciidoctor 由 Ruby 编写，打包成 RubyGem，然后发布到 {uri-rubygem}[RubyGems.org] 上。
+这个 gem 还被包含道几个 Linux 发行版中，其中包括 Fedora、Debian 和 Ubuntu。
+Asciidoctor 是开源的，{uri-repo}[代码]托管在 GitHub，遵从 {uri-license}[MIT] 协议。
+
+该文档有如下语言的翻译版：
+
+* {uri-rel-file-base}README.adoc[English]
+* {uri-rel-file-base}README-fr.adoc[Français]
+* {uri-rel-file-base}README-jp.adoc[日本語]
+
+.关键文档
+[.compact]
+* {uri-docs}/what-is-asciidoc[Asciidoctor 是什么？]
+* {uri-docs}/asciidoc-writers-guide[AsciiDoc 写作指南]
+* {uri-docs}/asciidoc-syntax-quick-reference[AsciiDoc 语法快速参考]
+* {uri-docs}/user-manual[Asciidoctor 用户手册]
+
+.Ruby 所至， Asciidoctor 相随
+****
+使用 JRuby 让 Asciidoctor 运行在 Java 虚拟机上。
+使用 {uri-asciidoctorj}[AsciidoctorJ] 直接调用 Asciidoctor 的 API 运行在 Java 或者其他 Java 虚拟机中。
+基于 AsciidoctorJ 有好多插件可用，这些插件可以将 Asciidoctor 整合到 Apache Maven，Gradle 或 Javadoc 构建中。
+
+Asciidoctor 也可以运行在 JavaScript 上。
+我们可以使用 http://opalrb.org[Opal] 将 Ruby 源码编译成 JavaScript 生成 {uri-asciidoctorjs}[Asciidoctor.js] 文件，这是一个全功能版的 Asciidoctor，可以运行在任意的 JavaScript 环境中，比如 Web 浏览器 或 Node.js。
+Asciidoctor.js 被用于预览 AsciiDoc，支持 Chrome 扩展，Atom，Brackets 或其他基于 Web 的工具。
+****
+
+ifdef::status[]
+.*Project health*
+image:https://img.shields.io/travis/asciidoctor/asciidoctor/master.svg[Build Status (Travis CI), link=https://travis-ci.org/asciidoctor/asciidoctor]
+image:https://ci.appveyor.com/api/projects/status/ifplu67oxvgn6ceq/branch/master?svg=true&amp;passingText=green%20bar&amp;failingText=%23fail&amp;pendingText=building%2E%2E%2E[Build Status (AppVeyor), link=https://ci.appveyor.com/project/asciidoctor/asciidoctor]
+//image:https://img.shields.io/coveralls/asciidoctor/asciidoctor/master.svg[Coverage Status, link=https://coveralls.io/r/asciidoctor/asciidoctor]
+//image:https://codeclimate.com/github/asciidoctor/asciidoctor/badges/gpa.svg[Code Climate, link="https://codeclimate.com/github/asciidoctor/asciidoctor"]
+image:https://inch-ci.org/github/asciidoctor/asciidoctor.svg?branch=master[Inline docs, link="https://inch-ci.org/github/asciidoctor/asciidoctor"]
+endif::[]
+
+[#the-big-picture]
+== 整体概况
+
+Asciidoctor 以纯文本格式读取内容，见下图左边的面板，并将它转换成 HTML5 呈现在右侧面板中。
+Asciidoctor 将默认的样式表应用到 HTML5 文档上，提供一个愉快的开箱即用的体验。
+
+image::{image-uri-screenshot}[AsciiDoc 源文预览和相应的 HTML 渲染]
+
+[#asciidoc-processing]
+== AsciiDoc Processing
+
+Asciidoctor 会读取并处理用 AsciiDoc 语法写的文件，然后将解析出来的解析树参数交给内置的转化器去生成 HTML5，DocBook 5 (或 4.5) 或帮助手册页面输出。
+你可以选择使用你自己的转化器或者加载 {uri-tilt}[Tilt] - 支持通过模板来自定义输出或产生附加的格式。
+
+NOTE: Asciidoctor是为了直接替换原 AsciiDoc Python 处理器（`asciidoc.py`）。
+Asciidoctor 测试套件含有 {uri-tests}[> 1,600 测试示例] 来确保和 AsciiDoc 语法的兼容性。
+
+除了传统的 AsciiDoc 语法，Asciidoctor 还添加额外的标记和格式设置选项，例如 font-based 图标（例如： `+icon:fire[]+`）和 UI 元素（例如： `+button:[Save]+`）。
+Asciidoctor 还提供了一个基于 {uri-foundation}[Foundation] 的现代化的、响应式主题来美化 HTML5 输出。
+
+[#requirements]
+== 要求
+
+Asciidoctor 可以运行在 Linux，OSX (Mac) 和 Windows 系统，但需要安装下面任意一个 {uri-ruby}[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。
+
+请参考 <<{idprefix}contributing,Contributing>> 来了解如何参与。
+
+[CAUTION]
+====
+如果在非英语的 Windows 环境，当你去调用 Asciidoctor 时，可能会碰到 `Encoding::UndefinedConversionError` 的错误提示。
+为了解决这个问题，我们建议将控制台的编码更改为 UTF-8：
+
+ chcp 65001
+
+一旦你做了这个改变，所有的编码问题，都将迎刃而解。
+如果你使用的是像 Eclipse 这样的 IDE 集成开发工具，你也需要确保他被你设置为 UTF-8 编码。
+使用 UTF-8 能使 Asciidoctor 在任何地方都能正常工作。
+====
+
+[#installation]
+== 安装
+
+Asciidoctor 可以通过三种方式安装（a）`gem install` 命令；（b）Bundler打包编译；（c）流行的 Linux 发行版的包管理器
+
+TIP: 使用 Linux 包管理器安装的好处是如果你机器在之前没有安装 Ruby 和 RubyGems 库，当你选择这种方式安装时它们会一并安装上去。
+不利的是在 gem 发布之后，这类安装包并不是立即可用。
+如果你需要安装最新版，你应该总是优先使用 `gem` 命令安装。
+
+[#a-gem-install]
+=== (a) gem 安装
+
+打开一个终端输入如下命令（不含开头的 `$`）：
+
+ $ gem install asciidoctor
+
+如果想安装一个预览版（比如：候选发布版），请使用：
+
+ $ gem install asciidoctor --pre
+
+.升级
+[TIP]
+====
+如果你安装有的是旧版本 Asciidoctor，你可以使用下面的命令来升级：
+
+ $ gem update asciidoctor
+
+如果使用 `gem install` 命令来安装一个新版本的 gem 来代替升级，会安装多个版本。
+这种情况，你可以使用下面的 gem 命令来移除旧版本：
+
+ $ gem cleanup asciidoctor
+====
+
+[#b-bundler]
+=== (b) Bundler
+
+. 在项目的根目录（或者当前路径），创建一个 `Gemfile` 文件；
+. 在这个文件中添加 `asciidoctor` gem 如下：
++
+[source,subs=attributes+]
+----
+source 'https://rubygems.org'
+gem 'asciidoctor'
+# 或者明确指明版本
+# gem 'asciidoctor', '{release-version}'
+----
+
+. 保存 `Gemfile` 文件
+. 打开终端，使用如下命令安装 gem：
+
+ $ bundle
+
+要升级 gem 的话，在 `Gemfile` 文件中，指明新版本，然后再次运行 `bundle` 即可。
+*不推荐* 直接使用 `bundle update` 命令，因为它还会升级其他 gem，也许会造成不可预料的结果。
+
+[#c-linux-package-managers]
+=== (c) Linux 包管理
+
+[#dnf-fedora-21-or-greater]
+==== DNF (Fedora 21 或更高版本)
+
+在 Fedora 21 或更高版本中安装这个 gem，可以使用 dnf。打开终端并输入如下命令：
+
+ $ sudo dnf install -y asciidoctor
+
+升级则使用：
+
+ $ sudo dnf update -y asciidoctor
+
+TIP: 如果你的 Fedora 系统配置的是自动升级包，在这种情况下，不需要你亲自动手升级。
+
+[#apt-get-debian-ubuntu-mint]
+==== apt-get (Debian, Ubuntu, Mint)
+
+在 Debian，Ubuntu 或 Mint 中安装这个 gem，请打开终端并输入如下命令：
+
+ $ sudo apt-get install -y asciidoctor
+
+升级则使用：
+
+ $ sudo apt-get upgrade -y asciidoctor
+
+TIP: 如果你的 Debian 或 Ubuntu 系统配置的是自动升级包，在这种情况下，不需要你亲自动手升级。
+
+使用包管理器（ apt-get ）安装的 Asciidoctor 的版本也许不是最新发布版。
+请查看发行版的包库，来确定每个发行版是打包的哪个版本。
+
+* https://packages.debian.org/search?keywords=asciidoctor&searchon=names&exact=1&suite=all&section=all[Debian 发行版中的 asciidoctor]
+* http://packages.ubuntu.com/search?keywords=asciidoctor&searchon=names&exact=1&suite=all&section=all[Ubuntu 发行版中的 asciidoctor]
+* https://community.linuxmint.com/software/view/asciidoctor[Mint 发行版中的 asciidoctor]
+
+[CAUTION]
+====
+我们建议不要使用 `gem update` 来升级包管理的 gem。
+这样做会使系统进入不一致的状态，包管理工具将不再跟踪相关文件（通常安装在 /usr/local 下。）
+简单地说，系统的 gem 只能由包管理器进行管理。
+
+如果你想使用一个比包管理器安装的更新版本的 Asciidoctor，你应该使用 http://rvm.io[RVM] 在你的用户家目录（比如：用户空间）下安装 Ruby。
+然后，你就可以放心地使用 `gem` 命令来安装或者更新 Asciidoctor gem。
+当使用 RVM 时，gem 将被安装到与系统隔离的位置。
+====
+
+[#apk-alpine-linux]
+==== apk (Alpine Linux)
+
+在 Alpine Linux 中安装这个 gem，请打开终端并输入如下命令：
+
+ $ sudo apk add asciidoctor
+
+升级则使用：
+
+ $ sudo apk add -u asciidoctor
+
+TIP: 如果你的 Alpine Linux 系统配置的是自动升级包，在这种情况下，不需要你亲自动手升级。
+
+[#other-installation-options]
+=== 其他安装选项
+
+* {uri-install-docker}[使用 Docker 安装 Asciidoctor ]
+* {uri-install-osx-doc}[在 Mac OS X 安装 Asciidoctor ]
+
+[#usage]
+== 使用
+
+如果成功安装 Asciidoctor，则在可执行程序路径中，`asciidoctor` 就可用了。
+为了验证它的可用性，你可以在终端中执行如下命令：
+
+ $ asciidoctor --version
+
+你应该看到关于 Asciidoctor 和 Ruby 环境信息将打印到你的终端上。
+
+[.output,subs=attributes+]
+....
+Asciidoctor {release-version} [http://asciidoctor.org]
+Runtime Environment (ruby 2.4.1p111 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
+....
+
+Asciidoctor 还提供了一套 API。
+这套 API 是为了整合其他的 Ruby 软件，例如 Rails、Sinatra、Github，甚至其他语言，比如 Java （通过 {uri-asciidoctorj}[AsciidoctorJ]） 和 JavaScript （通过 {uri-asciidoctorjs}[Asciidoctor.js]）。
+
+[#command-line-interface-cli]
+=== 命令行（CLI）
+
+`asciidoctor` 命令可以让你通过命令行（比如：终端）来调用 Asciidoctor。
+
+下面的命令将 README.adoc 文件转化为 HTML，并且保存到同一目录下的 README.html 文件中。
+生成的 HTML 文件名源自源文件名，只是将其扩展名改为了 `.html`。
+
+ $ asciidoctor README.adoc
+
+您可以通过添加各种标志和开关控制 Asciidoctor 处理器，通过下面的命令你可以学习它的更多用法：
+
+ $ asciidoctor --help
+
+比如，将文件写入到不同路径里，使用如下命令：
+
+ $ asciidoctor -D output README.adoc
+
+`asciidoctor` {uri-manpage}[帮助页面] 提供了这个命令的完整参考。
+
+点击下面的资源，学习更多关于 `asciidoctor` 命令的用法。
+
+* {uri-render-doc}[如何转化文档？]
+* {uri-themes-doc}[如何使用 Asciidoctor 样式工厂来创建自定义主题？]
+
+[#ruby-api]
+=== Ruby API
+
+为了在你应用中使用 Asciidoctor，首先需要引入这个 gem：
+
+[source]
+require 'asciidoctor'
+
+然后，你可以通过下面的代码将 AsciiDoc 源文件转化成一个 HTML 文件：
+
+[source]
+Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe
+
+WARNING: 当你通过 API 使用 Asciidoctor 时，默认的安全模式是 `:secure`。
+在 secure 模式下，很多核心特性将不可用，包括 `include` 特性。
+如果你想启用这些特性，你需要明确设置安全模式为 `:server` （推荐）或 `:safe`。
+
+你也可以将 AsciiDoc 字符串转化我内嵌的 HTML （为了插入到一个 HTML 页面），用法如下：
+
+[source]
+----
+content = '_Zen_ in the art of writing http://asciidoctor.org[AsciiDoc].'
+Asciidoctor.convert content, safe: :safe
+----
+
+如果你想得到完整的 HTML 文档，只需要启用 `header_footer` 选项即可。如下：
+
+[source]
+----
+content = '_Zen_ in the art of writing http://asciidoctor.org[AsciiDoc].'
+html = Asciidoctor.convert content, header_footer: true, safe: :safe
+----
+
+如果你想访问已经处理过的文档，可以将转化过程拆分成离散的几步：
+
+[source]
+----
+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 支持自定义转化器，它可以操作从待处理文件到生成文档整个环节。
+
+一个简单的、细微地自定义输出的方式是使用模板转化器。
+模板转化器运行你提供一个 {uri-tilt}[Tilt] 模板，这样通过模板文件来操作转化出的文档的每个节点。
+
+这样，你就 _可以_ 百分之百地控制你的输出。
+关于更多关于 API 或自定义输出信息，请参考 {uri-user-manual}[用户帮助手册]。
+
+[#contributing]
+== 贡献
+
+自由软件的精神鼓励 _每个人_ 来帮助改善这个项目。
+如果你在源码、文档或网站内容中发现错误或漏洞，请不要犹豫，提交一个议题或者推送一个修复请求。
+随时欢迎新的贡献者！
+
+这里有几种 *你* 可以做出贡献的方式：
+
+* 使用预发布版本（alpha, beta 或 preview）
+* 报告 Bug
+* 提议新功能
+* 编写文档
+* 编写规范
+* 编写 -- _任何补丁都不小。_
+** 修正错别字
+** 添加评论
+** 清理多余空白
+** 编写测试！
+* 重构代码
+* 修复 {uri-issues}[issues]
+* 审查补丁
+
+{uri-contribute}[贡献指南]提供了如何提供贡献，包括如何创建、修饰和提交问题、特性、需求、代码和文档给 Asciidoctor 项目。
+
+[#getting-help]
+== 获得帮助
+
+开发 Asciidoctor 项目是未来了帮助你更容易地书写和发布你的内容。
+但是，如果没有反馈，我们将寸步难行。
+我们鼓励你在讨论组、Twitter或聊天室里，提问为题，讨论项目的方方面面，
+
+讨论组 (Nabble):: {uri-discuss}
+Twitter:: https://twitter.com/search?f=tweets&q=%23asciidoctor[#asciidoctor] 来加入话题 或 https://twitter.com/asciidoctor[@asciidoctor] at并提醒我们
+聊天 (Gitter):: image:https://badges.gitter.im/Join%20In.svg[Gitter, link=https://gitter.im/asciidoctor/asciidoctor]
+
+ifdef::env-github[]
+Further information and documentation about Asciidoctor can be found on the project's website.
+
+{uri-project}/[Home] | {uri-news}[News] | {uri-docs}[Docs]
+endif::[]
+
+Asciidoctor 组织在 Github 托管代码、议案跟踪和相关子项目。
+
+代码库 (git):: {uri-repo}
+议案跟踪:: {uri-issues}
+在 GitHub 的 Asciidoctor 组织:: {uri-org}
+
+[#copyright-and-licensing]
+== 版权和协议
+
+Copyright (C) 2012-2018 Dan Allen, Ryan Waldron and the Asciidoctor Project.
+这个软件的免费使用是在MIT许可条款授予的。
+
+请看 {uri-license}[版权声明] 文件来获取更多详细信息。
+
+[#authors]
+== 作者
+
+*Asciidoctor* 由 https://github.com/mojavelinux[Dan Allen] 和 https://github.com/graphitefriction[Sarah White] 领导，并从 Asciidoctor 社区的 {uri-contributors}[很多其他独立开发者] 上收到了很多贡献。
+项目最初由 https://github.com/erebor[Ryan Waldron] 于 2012年基于 https://github.com/nickh[Nick Hengeveld] 的 {uri-prototype}[原型] 创建。
+
+*AsciiDoc* 由 Stuart Rackham 启动，并从 AsciiDoc 社区的其他独立开发者上收到很多贡献。
+
+== Changelog
+
+请看 {uri-changelog}[CHANGELOG]。

data/README.adoc

@@ -0,0 +1,454 @@
+= Asciidoctor
+Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Ryan Waldron <https://github.com/erebor[@erebor]>
+v1.5.7, 2018-05-02
+// settings:
+:idprefix:
+:idseparator: -
+:source-language: ruby
+:language: {source-language}
+ifndef::env-github[:icons: font]
+ifdef::env-github[]
+:status:
+:outfilesuffix: .adoc
+:caution-caption: :fire:
+:important-caption: :exclamation:
+:note-caption: :paperclip:
+:tip-caption: :bulb:
+:warning-caption: :warning:
+endif::[]
+// Variables:
+:release-version: 1.5.7
+// URIs:
+:uri-org: https://github.com/asciidoctor
+:uri-repo: {uri-org}/asciidoctor
+:uri-asciidoctorj: {uri-org}/asciidoctorj
+:uri-asciidoctorjs: {uri-org}/asciidoctor.js
+:uri-project: https://asciidoctor.org
+ifdef::env-site[:uri-project: link:]
+:uri-docs: {uri-project}/docs
+:uri-news: {uri-project}/news
+:uri-manpage: {uri-project}/man/asciidoctor
+:uri-issues: {uri-repo}/issues
+:uri-contributors: {uri-repo}/graphs/contributors
+:uri-rel-file-base: link:
+:uri-rel-tree-base: link:
+ifdef::env-site[]
+:uri-rel-file-base: {uri-repo}/blob/master/
+:uri-rel-tree-base: {uri-repo}/tree/master/
+endif::[]
+:uri-changelog: {uri-rel-file-base}CHANGELOG.adoc
+:uri-contribute: {uri-rel-file-base}CONTRIBUTING.adoc
+:uri-license: {uri-rel-file-base}LICENSE
+:uri-tests: {uri-rel-tree-base}test
+:uri-discuss: http://discuss.asciidoctor.org
+:uri-irc: irc://irc.freenode.org/#asciidoctor
+:uri-rubygem: https://rubygems.org/gems/asciidoctor
+:uri-what-is-asciidoc: {uri-docs}/what-is-asciidoc
+:uri-user-manual: {uri-docs}/user-manual
+:uri-install-docker: https://github.com/asciidoctor/docker-asciidoctor
+//:uri-install-doc: {uri-docs}/install-toolchain
+:uri-install-macos-doc: {uri-docs}/install-asciidoctor-macos
+:uri-render-doc: {uri-docs}/render-documents
+:uri-themes-doc: {uri-docs}/produce-custom-themes-using-asciidoctor-stylesheet-factory
+:uri-gitscm-repo: https://github.com/git/git-scm.com
+:uri-prototype: {uri-gitscm-repo}/commits/master/lib/asciidoc.rb
+:uri-freesoftware: https://www.gnu.org/philosophy/free-sw.html
+:uri-foundation: https://foundation.zurb.com
+:uri-tilt: https://github.com/rtomayko/tilt
+:uri-ruby: https://www.ruby-lang.org
+// images:
+:image-uri-screenshot: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/screenshot.png
+
+{uri-project}[Asciidoctor] is a _fast_ text processor and publishing toolchain for converting {uri-what-is-asciidoc}[AsciiDoc] content to HTML5, DocBook, PDF, and other formats.
+Asciidoctor is written in Ruby, packaged and distributed as a gem to {uri-rubygem}[RubyGems.org], and packaged for popular Linux distributions, including Fedora, Debian, Ubuntu, and Alpine.
+Asciidoctor can be run on the JVM using AsciidoctorJ and in all JavaScript environments using Asciidoctor.js.
+Asciidoctor is {uri-license}[open source software] and {uri-repo}[hosted on GitHub].
+
+ifndef::env-site[]
+This document is also available in the following languages: +
+{uri-rel-file-base}README-zh_CN.adoc[汉语]
+|
+{uri-rel-file-base}README-fr.adoc[Français]
+|
+{uri-rel-file-base}README-jp.adoc[日本語]
+endif::[]
+
+.Key documentation
+[.compact]
+* {uri-docs}/what-is-asciidoc[What is AsciiDoc?]
+* {uri-docs}/asciidoc-writers-guide[AsciiDoc Writer's Guide]
+* {uri-docs}/user-manual[Asciidoctor User Manual]
+* {uri-docs}/asciidoc-syntax-quick-reference[AsciiDoc Syntax Reference]
+
+ifdef::status[]
+.*Project health*
+image:https://img.shields.io/travis/asciidoctor/asciidoctor/master.svg[Build Status (Travis CI), link=https://travis-ci.org/asciidoctor/asciidoctor]
+image:https://ci.appveyor.com/api/projects/status/ifplu67oxvgn6ceq/branch/master?svg=true&amp;passingText=green%20bar&amp;failingText=%23fail&amp;pendingText=building%2E%2E%2E[Build Status (AppVeyor), link=https://ci.appveyor.com/project/asciidoctor/asciidoctor]
+//image:https://img.shields.io/coveralls/asciidoctor/asciidoctor/master.svg[Coverage Status, link=https://coveralls.io/r/asciidoctor/asciidoctor]
+//image:https://codeclimate.com/github/asciidoctor/asciidoctor/badges/gpa.svg[Code Climate, link="https://codeclimate.com/github/asciidoctor/asciidoctor"]
+image:https://inch-ci.org/github/asciidoctor/asciidoctor.svg?branch=master[Inline docs, link="https://inch-ci.org/github/asciidoctor/asciidoctor"]
+endif::[]
+
+== Sponsors
+
+We want to recognize our generous sponsors, without whose support Asciidoctor would not be possible.
+Thank you sponsors for your dedication to improving the state of technical documentation!
+
+image:https://www.okta.com/sites/all/themes/Okta/images/blog/Logos/Okta_Logo_BrightBlue_Medium.png[Okta,280,link=https://developer.okta.com/signup?utm_source=asciidoctor&utm_medium=logo&utm_campaign=sponsor,title="Add User Auth to Your Apps in Minutes with Okta"]
+&nbsp; &nbsp; &nbsp;
+image:https://secure.gravatar.com/avatar/823717a797dbd78ceff7b26aa397f383.png?size=200[OpenDevise,100,link=https://opendevise.com,title="Let the Creators of Asciidoctor and Antora Help You to Accelerate Your Docs"]
+
+Major funding for Asciidoctor is provided by our *Change Makers*, https://developer.okta.com/signup?utm_source=asciidoctor&utm_medium=text-link&utm_campaign=sponsor[Okta] and https://opendevise.com[OpenDevise], and our *Strategy Sponsors*, Khronos Group and Linda Roberts.
+Additional funding is provided by our https://asciidoctor.org/supporters[Community Backers].
+
+You can support this project by becoming a sponsor on https://opencollective.com/asciidoctor[OpenCollective].
+
+== The Big Picture
+
+Asciidoctor reads content written in plain text, as shown in the panel on the left in the image below, and converts it to HTML5, as shown rendered in the right panel.
+Asciidoctor applies a default stylesheet to the HTML5 document to provide a pleasant out-of-the-box experience.
+
+image::{image-uri-screenshot}[Preview of AsciiDoc source and corresponding rendered HTML]
+
+== AsciiDoc Processing
+
+Asciidoctor reads and parses text written in the AsciiDoc syntax, then feeds the parse tree to a set of built-in converters to produce HTML5, DocBook 5 (or 4.5) or man(ual) page output.
+You have the option of using your own converter or loading {uri-tilt}[Tilt]-supported templates to customize the generated output or produce additional formats.
+
+NOTE: Asciidoctor is a drop-in replacement for the original AsciiDoc Python processor (`asciidoc.py`).
+The Asciidoctor test suite has {uri-tests}[> 2,000 tests] to ensure compatibility with the AsciiDoc syntax.
+
+In addition to the classic AsciiDoc syntax, Asciidoctor recognizes additional markup and formatting options, such as font-based icons (e.g., `+icon:fire[]+`) and UI elements (e.g., `+button:[Save]+`).
+Asciidoctor also offers a modern, responsive theme based on {uri-foundation}[Foundation] to style the HTML5 output.
+
+== Where Ruby goes, Asciidoctor follows
+
+You can run Asciidoctor on the JVM using JRuby.
+To invoke the Asciidoctor API directly from Java and other JVM languages, use {uri-asciidoctorj}[AsciidoctorJ].
+There are plugins available, based on AsciidoctorJ, that integrate the Asciidoctor processor into Apache Maven, Gradle or Javadoc builds.
+
+Asciidoctor also runs in JavaScript.
+We use https://opalrb.com[Opal] to transcompile the Ruby source to JavaScript to produce {uri-asciidoctorjs}[Asciidoctor.js], a fully-functional version of Asciidoctor that works in any JavaScript environment, such as a web browser or Node.js.
+Asciidoctor.js is used to power the AsciiDoc preview extensions for Chrome, Atom, Brackets and other web-based tooling.
+
+== Requirements
+
+Asciidoctor works on Linux, macOS and Windows and requires one of the following implementations of {uri-ruby}[Ruby]:
+
+* Ruby (MRI/CRuby 1.8.7 - 2.5)
+* JRuby (1.7 in Ruby 1.8 and 1.9 modes, 9000)
+* Rubinius 2.2.x
+* Opal (JavaScript)
+
+We welcome your help testing Asciidoctor on these and other platforms.
+Refer to the <<Contributing>> section to learn how to get involved.
+
+[CAUTION]
+====
+If you're using a non-English Windows environment, you may bump into an `Encoding::UndefinedConversionError` when invoking Asciidoctor.
+To solve this issue, we recommend changing the active code page in your console to UTF-8:
+
+ chcp 65001
+
+Once you make this change, all your Unicode headaches will be behind you.
+If you're using an IDE like Eclipse, make sure you set the encoding to UTF-8 there as well.
+Asciidoctor works best when you use UTF-8 everywhere.
+====
+
+== Installation
+
+Asciidoctor can be installed using (a) the `gem install` command, (b) Bundler, (c) package managers for popular Linux distributions, or (d) Homebrew for macOS.
+
+TIP: The benefit of using a Linux package manager to install the gem is that it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine.
+The drawback is that the package may not be available immediately after the release of the gem.
+If you need the latest version, you can always fallback to using the `gem` command.
+
+=== (a) gem install
+
+Open a terminal and type (excluding the leading `$`):
+
+ $ gem install asciidoctor
+
+If you want to install a pre-release version (e.g., a release candidate), use:
+
+ $ gem install asciidoctor --pre
+
+.Upgrading your installation
+[TIP]
+====
+If you have an earlier version of Asciidoctor installed, you can update it using:
+
+ $ gem update asciidoctor
+
+If you install a new version of the gem using `gem install` instead of gem update, you'll have multiple versions installed.
+If that's the case, use the following gem command to remove the old versions:
+
+ $ gem cleanup asciidoctor
+====
+
+=== (b) Bundler
+
+. Create a Gemfile in the root folder of your project (or the current directory)
+. Add the `asciidoctor` gem to your Gemfile as follows:
++
+[source,subs=attributes+]
+----
+source 'https://rubygems.org'
+gem 'asciidoctor'
+# or specify the version explicitly
+# gem 'asciidoctor', '{release-version}'
+----
+
+. Save the Gemfile
+. Open a terminal and install the gem using:
+
+ $ bundle
+
+To upgrade the gem, specify the new version in the Gemfile and run `bundle` again.
+Using `bundle update` is *not* recommended as it will also update other gems, which may not be the desired result.
+
+=== (c) Linux package managers
+
+==== DNF (Fedora 21 or greater)
+
+To install the gem on Fedora 21 or greater using dnf, open a terminal and type:
+
+ $ sudo dnf install -y asciidoctor
+
+To upgrade the gem, use:
+
+ $ sudo dnf update -y asciidoctor
+
+TIP: Your system may be configured to automatically update rpm packages, in which case no action is required by you to update the gem.
+
+==== apt-get (Debian, Ubuntu, or Mint)
+
+To install the gem on Debian, Ubuntu or Mint, open a terminal and type:
+
+ $ sudo apt-get install -y asciidoctor
+
+To upgrade the gem, use:
+
+ $ sudo apt-get upgrade -y asciidoctor
+
+TIP: Your system may be configured to automatically update deb packages, in which case no action is required by you to update the gem.
+
+The version of Asciidoctor installed by the package manager (apt-get) may not match the latest release of Asciidoctor.
+Consult the package repository for your distribution to find out which version is packaged per distribution release.
+
+* https://packages.debian.org/search?keywords=asciidoctor&searchon=names&exact=1&suite=all&section=all[asciidoctor package by Debian release]
+* https://packages.ubuntu.com/search?keywords=asciidoctor&searchon=names&exact=1&suite=all&section=all[asciidoctor package by Ubuntu release]
+* https://community.linuxmint.com/software/view/asciidoctor[asciidoctor package by Mint release]
+
+[CAUTION]
+====
+You're advised against using the `gem update` command to update a gem managed by the package manager.
+Doing so puts the system into an inconsistent state as the package manager can no longer track the files (which get installed under /usr/local).
+Simply put, system gems should only be managed by the package manager.
+
+If you want to use a version of Asciidoctor that is newer than what is installed by the package manager, you should use https://rvm.io[RVM] to install Ruby in your home directory (i.e., user space).
+Then, you can safely use the `gem` command to install or update the Asciidoctor gem.
+When using RVM, gems are installed in a location isolated from the system.
+====
+
+==== apk (Alpine Linux)
+
+To install the gem on Alpine Linux, open a terminal and type:
+
+ $ sudo apk add asciidoctor
+
+To upgrade the gem, use:
+
+ $ sudo apk add -u asciidoctor
+
+TIP: Your system may be configured to automatically update apk packages, in which case no action is required by you to update the gem.
+
+=== (d) Homebrew (macOS)
+
+You can use Homebrew to install Asciidoctor on macOS.
+If you haven't yet installed Homebrew, follow the instructions at https://brew.sh/[brew.sh].
+
+Once Homebrew is installed, you can install the `asciidoctor` gem using the http://brewformulas.org/Asciidoctor[asciidoctor] package.
+To do so, open a terminal and type:
+
+ $ brew install asciidoctor
+
+To upgrade the gem, use:
+
+ $ brew update
+ $ brew upgrade asciidoctor
+
+TIP: Homebrew installs the `asciidoctor` gem into an exclusive prefix that's independent of system gems.
+
+=== Other installation options
+
+* {uri-install-docker}[Installing Asciidoctor using Docker]
+* {uri-install-macos-doc}[Installing Asciidoctor on macOS]
+// at the moment, the following entry is just a reiteration of the information in this README
+//* {uri-install-doc}[Installing the Asciidoctor toolchain]
+
+== Usage
+
+If the Asciidoctor gem installed successfully, the `asciidoctor` command line interface (CLI) will be available on your PATH.
+To verify it's available, run the following in your terminal:
+
+ $ asciidoctor --version
+
+You should see information about the Asciidoctor version and your Ruby environment printed in the terminal.
+
+[.output,subs=attributes+]
+....
+Asciidoctor {release-version} [https://asciidoctor.org]
+Runtime Environment (ruby 2.4.1p111 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
+....
+
+Asciidoctor also provides an API.
+The API is intended for integration with other Ruby software, such as Rails, Sinatra and GitHub, and other languages, such as Java (via {uri-asciidoctorj}[AsciidoctorJ]) and JavaScript (via {uri-asciidoctorjs}[Asciidoctor.js]).
+
+=== Command line interface (CLI)
+
+The `asciidoctor` command allows you to invoke Asciidoctor from the command line (i.e., a terminal).
+
+The following command converts the file README.adoc to HTML and saves the result to the file README.html in the same directory.
+The name of the generated HTML file is derived from the source file by changing its file extension to `.html`.
+
+ $ asciidoctor README.adoc
+
+You can control the Asciidoctor processor by adding various flags and switches, which you can learn about using:
+
+ $ asciidoctor --help
+
+For instance, to write the file to a different directory, use:
+
+ $ asciidoctor -D output README.adoc
+
+The `asciidoctor` {uri-manpage}[man page] provides a complete reference of the command line interface.
+
+Refer to the following resources to learn more about how to use the `asciidoctor` command.
+
+* {uri-render-doc}[How do I convert a document?]
+* {uri-themes-doc}[How do I use the Asciidoctor stylesheet factory to produce custom themes?]
+
+=== Ruby API
+
+To use Asciidoctor in your application, you first need to require the gem:
+
+[source]
+require 'asciidoctor'
+
+You can then convert an AsciiDoc source file to an HTML file using:
+
+[source]
+Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe
+
+WARNING: When using Asciidoctor via the API, the default safe mode is `:secure`.
+In secure mode, several core features are disabled, including the `include` directive.
+If you want to enable these features, you'll need to explicitly set the safe mode to `:server` (recommended) or `:safe`.
+
+You can also convert an AsciiDoc string to embeddable HTML (for inserting in an HTML page) using:
+
+[source]
+----
+content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
+Asciidoctor.convert content, safe: :safe
+----
+
+If you want the full HTML document, enable the `header_footer` option as follows:
+
+[source]
+----
+content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
+html = Asciidoctor.convert content, header_footer: true, safe: :safe
+----
+
+If you need access to the parsed document, you can split the conversion into discrete steps:
+
+[source]
+----
+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
+----
+
+Keep in mind that if you don't like the output Asciidoctor produces, _you can change it!_
+Asciidoctor supports custom converters that can handle converting from the parsed document to the generated output.
+
+One easy way to customize the output piecemeal is by using the template converter.
+The template converter allows you to supply a {uri-tilt}[Tilt]-supported template file to handle converting any node in the document.
+
+However you go about it, you _can_ have 100% control over the output.
+For more information about how to use the API or to customize the output, refer to the {uri-user-manual}[user manual].
+
+== Contributing
+
+In the spirit of {uri-freesoftware}[free software], _everyone_ is encouraged to help improve this project.
+If you discover errors or omissions in the source code, documentation, or website content, please don't hesitate to submit an issue or open a pull request with a fix.
+New contributors are always welcome!
+
+Here are some ways *you* can contribute:
+
+* by using prerelease (alpha, beta or preview) versions
+* by reporting bugs
+* by suggesting new features
+* by writing or editing documentation
+* by writing specifications
+* by writing code -- _No patch is too small._
+** fix typos
+** add comments
+** clean up inconsistent whitespace
+** write tests!
+* by refactoring code
+* by fixing {uri-issues}[issues]
+* by reviewing patches
+
+The {uri-contribute}[Contributing] guide provides information on how to create, style, and submit issues, feature requests, code, and documentation to the Asciidoctor Project.
+
+== Getting Help
+
+The Asciidoctor project is developed to help you easily write and publish your content.
+But we can't do it without your feedback!
+We encourage you to ask questions and discuss any aspects of the project on the discussion list, on Twitter or in the chat room.
+
+Discussion list (Nabble):: {uri-discuss}
+Twitter:: https://twitter.com/search?f=tweets&q=%23asciidoctor[#asciidoctor] hashtag or https://twitter.com/asciidoctor[@asciidoctor] mention
+Chat (Gitter):: image:https://badges.gitter.im/Join%20In.svg[Gitter, link=https://gitter.im/asciidoctor/asciidoctor]
+////
+Chat (IRC):: {uri-irc}[#asciidoctor] on FreeNode IRC
+////
+
+ifdef::env-github[]
+Further information and documentation about Asciidoctor can be found on the project's website.
+
+{uri-project}[Home] | {uri-news}[News] | {uri-docs}[Docs]
+endif::[]
+
+The Asciidoctor organization on GitHub hosts the project's source code, issue tracker, and sub-projects.
+
+Source repository (git):: {uri-repo}
+Issue tracker:: {uri-issues}
+Asciidoctor organization on GitHub:: {uri-org}
+
+== Copyright and Licensing
+
+Copyright (C) 2012-2018 Dan Allen, Ryan Waldron and the Asciidoctor Project.
+Free use of this software is granted under the terms of the MIT License.
+
+See the {uri-license}[LICENSE] file for details.
+
+== Authors
+
+*Asciidoctor* is led by https://github.com/mojavelinux[Dan Allen] and https://github.com/graphitefriction[Sarah White] and has received contributions from {uri-contributors}[many other individuals] in Asciidoctor's awesome community.
+The project was initiated in 2012 by https://github.com/erebor[Ryan Waldron] and based on {uri-prototype}[a prototype] written by https://github.com/nickh[Nick Hengeveld].
+
+*AsciiDoc* was started by Stuart Rackham and has received contributions from many other individuals in the AsciiDoc community.
+
+ifndef::env-site[]
+== Changelog
+
+ifeval::[{safe-mode-level} < 20]
+include::CHANGELOG.adoc[tag=compact,leveloffset=+1]
+endif::[]
+
+Refer to the {uri-changelog}[CHANGELOG] for a complete list of changes in older releases.
+endif::[]