# asciidoctor **Repository Path**: anydev/asciidoctor ## Basic Information - **Project Name**: asciidoctor - **Description**: 一个 Ruby 开发的 AsciiDoc 文本处理与发布工具，可以将 AsciiDoc 文档转化成 HTML、DocBook、PDF、EPUB 等等多种便于发布的格式。AsciiDoc 相较于 Markdown 更加灵活，可以轻松支持目录、注意事项、数学符号、代码高亮等功能，适用于编写用户手册和书籍等场景。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: feature/html-converter-next - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2024-10-08 - **Last Updated**: 2024-10-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README = Asciidoctor Dan Allen ; Sarah White // 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.20 // 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，参见 <>。 ==== 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 然后参照 <>。 ==== Rubyinstaller 或者你可以使用 https://rubyinstaller.org/downloads/[Rubyinstaller]，下载它，然后参照 <>。 [#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::[]