开启 AsciiDoc 规范之旅

作者 Sarah White 和 Dan Allen -

在过去一年中，社区对 AsciiDoc 规范的呼声此起彼伏，很明显，大家已经准备好让 AsciiDoc 迈出这一步。我们也这么认为。我们还联系了 AsciiDoc 的创始人 Stuart，他也表示支持。所以，现在是时候着手此事了。

在 Eclipse Foundation 拥有新家

我们希望 AsciiDoc 能有一个光明的未来，并拥有发展壮大所需的资源。为了实现这一目标，我们决定向 Eclipse Foundation 提交一份 AsciiDoc 语言规范提案。Eclipse Foundation 为规范的制定提供了一个平台，并致力于透明和开源，这些价值观与 AsciiDoc 及其社区高度契合。Eclipse Foundation 规范流程 (EFSP) 提供了一个清晰但可自定义的结构，降低了流程停滞的风险，并确保了结果在实际世界中的可用性。该流程是公开的、供应商中立的，所有源材料和最终产物都是开源的。

AsciiDoc 成为规范意味着什么？

AsciiDoc 语言规范将包括一个开源的规范文档，其中定义了必需和可选的 API 定义、语义行为、数据格式和协议，以及一个开源的技术兼容性套件 (TCK)，开发人员可以使用它来开发和测试兼容的实现。（熟悉 Asciidoctor 的 Dan 和我的人都知道，一个开源的 TCK 是我们的硬性要求）。根据 EFSP 的定义，兼容的实现必须完全实现规范版本的所有非可选元素，必须满足相应 TCK 的所有要求，并且不得更改指定的 API。

对于用户和开发者来说，AsciiDoc 规范都将意味着一个清晰、可用的 AsciiDoc 定义及其解释方式。开发者将能够围绕 AsciiDoc 构建实现、工具和服务，而不会有稀释其含义或分裂它的风险。反过来，用户将拥有更多的选择、更高的文档可移植性，并确保兼容的实现和工具能够按照版本化的规范处理他们的 AsciiDoc 文档。

Asciidoctor 将何去何从？

我们计划让 Asciidoctor (RubyGem) 成为 AsciiDoc (规范) 的独立、兼容的实现。（这并不意味着 Asciidoctor 的整体将迁移到 Eclipse Foundation）。为了通过 TCK 测试，这可能意味着 Asciidoctor 中需要添加、删除或更改功能，以满足规范的必需和可选元素。Asciidoctor.js 和 AsciidoctorJ 项目，如果他们选择这样做，也可以决定成为独立的、兼容的实现，并且拥有比以前更大的自由度。这将为新兴的实现将 AsciiDoc 带到更多平台腾出空间。

一旦规范流程开始进行，我们将了解更多信息，并及时向您通报预期情况。

准备好了吗？开始吧！

创建 AsciiDoc 规范的下一步是将其作为一个规范项目提交给 Eclipse Foundation。我和 Dan（作为 OpenDevise，代表 Asciidoctor）计划提交的提案将由 Eclipse 管理组织审查，然后发布供社区审查和评论。想了解更多关于规范流程的信息，我鼓励您查看 Wayne Beaton 的博文 第二部分：EFSP 和 第三部分：创建。规范流程是 Eclipse 开发流程 (EDP) 的一个分支，您可以在 第一部分：EDP 中阅读。您也可以阅读 EFSP 文档。

通过一个可以适应 AsciiDoc 社区需求的规范流程，我和 Dan 相信该语言将以可持续且实质性的方式发展，从而跟上社区当前和未来的需求。我们非常期待开始，希望您能加入我们，共同努力，让 AsciiDoc 成为一项规范！

切换到语义化版本控制

作者 Dan Allen -

经过多年的讨论，我们终于准备好在 Asciidoctor 中切换到语义化版本控制。这次切换将作为每个参与项目下一次重大发布的一部分。

关于语义化版本控制

语义化版本控制（或简称 SemVer）是一个基于简单的 MAJOR.MINOR.PATCH 顺序选择版本号的逻辑系统。

  • MAJOR 版本用于引入不兼容的更改（无论大小）。

  • MINOR 版本用于添加向后兼容的功能。

  • PATCH 版本用于修复 Bug（当然是向后兼容的）。

还可以通过构建元数据为预发布版本留出空间。您可以在 https://semver.org 上了解更多信息。

在我们当前的系统中，补丁发布与主版本和次版本发布无法区分，并且只有一个发布线。经验告诉我们（以艰难的方式），这种情况既不清晰也不可持续。对我们而言，SemVer 旨在实现更好的沟通和发展空间。它是一个基于共享期望和信任的系统。虽然它可能不完美，但 SemVer 应该有助于理解版本号的含义以及何时进行升级。我们不能期望它能防止破坏，但至少您会知道何时可能发生。

独立版本化项目

切换到 SemVer 也意味着 Asciidoctor 项目，即 Asciidoctor、AsciidoctorJ 和 Asciidoctor.js，将独立进行版本控制。生态系统中的其他项目也可能会开始独立版本化（事实上，有些已经开始了）。

AsciidoctorJ 和 Asciidoctor.js 都已经发展到远远超出重新分发 Asciidoctor RubyGem 的阶段。它们拥有自己的 API、扩展模型、自定义功能和平台集成。这值得拥有自己的版本线。独立的版本线还将使用户能够更好地理解每个版本将带来什么。

在与 Robert (AsciidoctorJ 负责人) 和 Guillaume (Asciidoctor.js 负责人) 交流后，这是我们商定的系统：

  • 核心处理器（Asciidoctor、AsciidoctorJ 和 Asciidoctor.js）将从 2.0.0 版本开始迁移到 SemVer。我们计划这三个项目同时进行这次主版本迁移，以最大限度地减少混淆。

  • 如果 Asciidoctor.js 或 AsciidoctorJ 需要对 Asciidoctor 进行更改，它们可以强制 Asciidoctor 发布。这意味着 Asciidoctor 必须随时“准备发布”。补丁或次要版本发布不需要太多讨论，但主版本发布自然需要。

  • 2.0.0 之后，我们不会尝试在三个项目之间统一版本号。Guillaume 提出了一个有力的论点，认为尝试统一版本号会违背 SemVer 的原则，从而导致版本号失去意义。这确实会增加记录 Asciidoctor.js 或 AsciidoctorJ 所提供底层 Asciidoctor 版本的复杂性。然而，AsciidoctorJ 和 Asciidoctor.js 都提供了访问底层 Asciidoctor 版本号的 API。发布号也可以通过 asciidoctor-version 文档属性访问。

我们考虑过在坚持 SemVer 的同时，如何将 Asciidoctor、AsciidoctorJ 和 Asciidoctor.js 锁定到同一版本。然而，我们得出的结论是，这样做只会延续我们看到的版本发布积压的状况。最好让这些项目拥有在适当时机自由发布的自由。有了三个版本号段 (MAJOR.MINOR.PATCH)，我们终于有了足够的空间来实现这些发布！

后续步骤

我们将首先将 Asciidoctor 1.5.8 版本重新打包为 2.0.0，并进行一些小的调整以放弃不再支持的 Ruby 版本。然后 AsciidoctorJ 和 Asciidoctor.js 将会跟进发布它们的 2.0.0 版本。届时，我们将严格按照上述 SemVer 规则进行版本控制。

Asciidoctor 的资金支持

作者： Dan Allen 和 Sarah White -

借助 Asciidoctor，我们致力于塑造写作和出版的未来，尤其是在技术文档领域。我们希望人们使用开源，不仅因为它是最好的软件，还因为它是有史以来文档化最好的软件。

我们已经走了很长一段路。我们对未来有更大的计划。为了将我们的愿景变为现实，Asciidoctor 项目需要资金。

更新： 我们已将 Asciidoctor 项目的资金平台从 BountySource 迁移到 OpenCollective。如果您希望为 Asciidoctor 项目提供财务支持，请访问 OpenCollective 上的 Asciidoctor。

为了确保 Asciidoctor 项目的持续成功和可持续性，我们在 Bountysource 的新资金平台上为 Asciidoctor 设立了 一个账户。（Bountysource 类似于开源项目的 Kickstarter）。您可以在 Asciidoctor 活动页面 上阅读有关此活动的更多详细信息，包括其运作方式和我们的初始目标。

Salt 平台将使我们能够接受来自组织和个人的财务支持，并将资金以我们认为最适合项目的方式分配。它还将使我们能够完全透明地说明项目的资金来源。最初的目標是讓我和 Sarah 能够全職投入 Asciidoctor 的開發。

Asciidoctor growth

在过去的三年里，Asciidoctor 已经取得了长足的增长和成熟。它现在是文档的关键组成部分，尤其是在开源领域。为了跟上项目的增长速度，管理整个 Asciidoctor 生态系统，并促进参与，我们需要投入更多的时间和精力来完成这项工作。我们还需要支付当前和未来的基础设施成本。这个活动筹集的资金越多（持续不断地），我们就能取得越大的成就，解锁越多的可能性，Asciidoctor 就能产生越大的影响。

通过获得资金，Asciidoctor 项目可以实质上雇佣我和 Sarah 来保持其平稳运行，并更频繁地发布组件。我们热爱运营 Asciidoctor 项目，我们也热爱这个社区。我们希望继续为社区服务，并做我们所热爱的事情，打造一个作家们一直想要的工具链。

让我们一起实现吧！

如果您有任何问题或疑虑，请随时回复。

使用 Arquillian 和 Docker 验证 AsciidoctorJ 在 WildFly 中正常工作

作者：Maxime Gréau -

我们很高兴地宣布 Asciidoctor 大家庭的最新成员：Docker AsciidoctorJ。 Docker AsciidoctorJ 项目确保任何部署到 Java EE 应用服务器* 的应用程序都可以使用 AsciidoctorJ。

* 目前仅测试了 WildFly。欢迎提交拉取请求！

项目说明

该项目提供

一个 Dockerfile

构建一个包含 WildFly 8.2、AsciidoctorJ 1.5.2 和 AsciidoctorJ PDF 1.5.0 的 Docker 镜像

Arquillian 测试

在 Docker 容器中使用 AsciidoctorJ 将 AsciiDoc 文件转换为 HTML 和 PDF 文件

AsciidoctorJ WildFly Docker containers managed by Arquillian
图 1. Arquillian & Docker 在 WildFly 中集成测试 AsciidoctorJ 的强大功能

了解更多！

下 一篇博文 解释了我们如何在 WildFly Docker 容器中执行 AsciidoctorJ 的 Arquillian 测试。我们将讨论

想了解更多？阅读完整博文以获取所有详细信息。

Asciidoctor 中的纯文本图表成形！

作者：Pepijn Van Eeckhoudt -

您用纯文本写作。您用纯文本编码。为什么不也用纯文本创建图表呢？现在您可以使用 Asciidoctor Diagram 来做到这一点！

简介

Asciidoctor 是一个用于编写技术文档的出色工具。它让您能将更多时间花在内容上，而不是与所见即所得工具作斗争。

仍然会分散您注意力的任务之一，也是比应有的更困难的任务，就是将技术图表集成到您的文档中。它涉及启动 UML 或图表工具，在屏幕上调整像素以绘制图表，将结果导出为便于 Web 使用的图像格式，并在源文档中链接它们。Asciidoc 在视觉一致性、协作便利性等方面提供的许多好处，在处理图表时却不可用。

所有这些今天都随着 Asciidoctor Diagram 扩展的发布而改变。 Asciidoctor Diagram 将现有的纯文本语法图表工具集成到 Asciidoctor 处理流程中。这意味着您可以将图表的源代码直接嵌入到您的文档中！

Asciidoctor Diagram 的第一个版本支持以下图表语言

这些“轻量级图表语言”对于图形图表来说，就像 AsciiDoc 对于 HTML 一样。换一种说法

language analogy diagram

您的第一个纯文本图表

将图表添加到文档中最简单的方法是使用图表块。只需在文件中添加一个列表块，将适当的语法名称（ditaa、graphviz 或 plantuml）作为块名称（也称为样式）。

[ditaa]
----
                   +-------------+
                   | Asciidoctor |-------+
                   |  Diagram    |       |
                   +-------------+       | PNG out
                       ^                 |
                       | ditaa in        |
                       |                 v
 +--------+   +--------+----+    /----------------\
 |        | --+ Asciidoctor +--> |                |
 |  Text  |   +-------------+    |Beautiful output|
 |Document|   |   !magic!   |    |                |
 |     {d}|   |             |    |                |
 +---+----+   +-------------+    \----------------/
     :                                   ^
     |          Lots of work             |
     +-----------------------------------+
----

当 Asciidoctor Diagram 扩展处理此类型的块时，它将读取块的内容，将其传递给 ditaa 库，将生成的图像写入磁盘，并生成一个图像块。它在渲染的文档中显示如下

sample ditaa diagram

神奇！

生成这些图像之一速度很快，但如果您开始在文档中添加大量图表，处理时间可能会累加。Asciidoctor Diagram 通过跟踪 *.cache 文件中的图表元数据来优化处理，并且仅在图表源代码被修改时才重新生成图像。这使得文档的增量渲染过程保持快速。

控制输出

默认情况下，Asciidoctor Diagram 创建 PNG 图像，并根据图表源代码自动计算输出文件名。可以使用 target 和 format 属性覆盖此行为。您可以将这些属性指定为第一个和第二个位置属性，或作为显式命名的属性。以下是如何生成具有特定名称的 SVG 文件，该文件为 Graphviz 图形

[graphviz, dot-example, svg]
----
digraph g {
    a -> b
    b -> c
    c -> d
    d -> a
}
----

神奇发生后，您将看到

sample graphviz diagram
Asciidoctor Diagram 捆绑了 ditaa 和 PlantUML 库，并将使用它们来生成图表。为了生成 Graphviz 图表，您必须单独安装它（这意味着 dot 命令必须在您的 PATH 中可用）。

Asciidoctor Diagram 将图表块转换为图像块并应用任何其他属性。这意味着您可以使用标准的 Asciidoctor 功能来控制生成图像的定位。块标题和 ID 也可以以同样的方式分配。

[[main-classes]]
.The PlantUML block extension class
[plantuml, sample-plantuml-diagram, alt="Class diagram", width=135, height=118]
----
class BlockProcessor
class PlantUmlBlock
BlockProcessor <|-- PlantUmlBlock
----

以下是渲染的内容

Class diagram
PlantUML 块扩展类

包含外部图表

将图表的源代码嵌入到文档中可能并不总是可取的。也可以使用块宏语法处理外部图表。这与您通常在文档中包含图像的方式非常相似。

plantuml::classes.txt[format=svg, alt="Class diagram", width=300, height=200]

启用扩展

Asciidoctor 0.1.4 尚不支持通过命令行启用扩展。这是 Asciidoctor 1.5.0 即将推出的功能。在此之前，启用扩展的最简单方法是使用一个简短的包装脚本。下面的脚本 asciidoctor-diagram 会加载并注册 Asciidoctor Diagram 扩展，然后像 asciidoctor 命令一样调用 Asciidoctor。

asciidoctor-diagram 启动脚本
#!/usr/bin/env ruby

require 'asciidoctor' (1)
require 'asciidoctor/cli/options'
require 'asciidoctor/cli/invoker'

require 'asciidoctor-diagram' (2)

invoker = Asciidoctor::Cli::Invoker.new ARGV (3)
invoker.invoke!
exit invoker.code
1 加载 Asciidoctor
2 加载并注册 Asciidoctor Diagram 扩展
3 调用 Asciidoctor CLI

将 asciidoctor-diagram 脚本放到您的 PATH 中，使其可执行，并用它代替 asciidoctor 命令。

$ asciidoctor-diagram my-doc-with-cool-diagrams.adoc

在文档上运行 asciidoctor-diagram 脚本后，去看看它为您制作的酷炫图表吧！

开始玩吧！

现在是时候开始玩 Asciidoctor Diagram 了。探索它的功能以及如何改进它。为了帮助您入门，请查看 Asciidoctor Diagram 存储库中的这些示例。我们期待在 Asciidoctor 讨论列表或 Asciidoctor Diagram 问题跟踪器上听到您的声音。

共同努力，让图表和文档从纯文本中焕发活力！

在浏览器中引入 Asciidoctor.js 实时预览

作者：Guillaume Grossetie -

我想向您介绍一种最简单的方法，可以在浏览器中直接渲染任何 AsciiDoc 文件，无论是本地还是远程！

您只需要安装 Chrome 扩展或 Firefox 附加组件。然后，您可以通过访问任何 AsciiDoc 文件来将其预览为 HTML！

工作原理

Chrome 扩展和 Firefox 附加组件使用 Asciidoctor.js 在浏览器内部将 AsciiDoc 渲染为 HTML。两者都提供一个切换按钮，用于在 HTML 输出和 AsciiDoc 源之间切换。

您可以在这里看到一个在 Chrome 中渲染的本地 AsciiDoc 文件。

chrome extension enabled
Chrome 扩展正在工作
您可以使用此扩展通过 Asciidoctor.js 查看 GitHub 上的任何 AsciiDoc 文件！只需在 GitHub 网页界面中导航到文件（尝试 此博文），然后单击文件预览上方出现的 Raw 按钮。看起来好多了，不是吗？

未来

目前，我们使用的是基于 Asciidoctor 0.1.2 的 Asciidoctor.js。我们计划将新发布的 Asciidoctor 0.1.4 交叉编译为 JavaScript，以支持最新最强大的功能！

我们还在开发一些很酷的新功能

  • 使用 MarkItUp! 进行基于浏览器的编辑器

  • 实时重新加载以在本地文件更改时自动刷新

  • 以及更多…

贡献

我们始终欢迎补丁、更好的文档、功能请求、宣传或您能提供的任何帮助。

OSCON 2013：更轻松的文档、更简单的网站和更快的协作

作者：Dan Allen -

您是否发现编写和协作文档或 Web 内容很困难？在 OSCON 2013 上，我们将与您一起，通过简化您的内容工作流程、教您如何更有效地协作以及帮助使写作和发布变得愉快，来减少创建内容的摩擦！

OSCON banner

加入我们在 7 月 23 日星期二举行的题为 更轻松的文档、更简单的网站和更快的协作 的研讨会，了解那些可以减轻您文档工作负担并启动您的内容策略的工具和技术。要参加，请注册 OSCON 2013，然后报名参加研讨会！

提示： 使用代码 ARQIKE 可享受 注册 20% 的折扣！

如何？

始于写作内容…

…用您写电子邮件的格式。

Plain text *embellished* with _subtle_ markup.

事实上，这就是轻量级标记语言 AsciiDoc 的重点。AsciiDoc 语法感觉自然，让您专注于内容。用 AsciiDoc 编写的内容易于以原始形式阅读和编辑，这有利于协作。它还可以被翻译成 HTML 进行呈现，实现 Web 发布！

Zurb Foundation Yeti

接下来，我们进行一些“烘焙”。

在用 AsciiDoc 编写了一些文档后，我们将使用静态网站生成器 Awestruct 和 Jekyll 将我们的内容整合到一个连贯的网站中。然后，我们将利用 Bootstrap 和 Zurb Foundation 等 CSS 框架来为内容增添优雅的外观和感觉。

一键发布！

然后，我们将使用单个命令 git push 将我们的网站发布到 GitHub Pages。

然后真正的乐趣就开始了。从 GitHub 开始，我们可以使用 git 和 GitHub 界面中的 Web 协作工具协作处理内容。

Revision history in GitHub
修订历史记录安全地保存在 git 存储库中。

别忘了分块！

数十亿设备已连接到 Web。而且数量还在不断增加。无论设备市场如何随时间变化，我们的挑战仍然是相同的。我们需要将我们的内容放到所有这些设备上。

AsciiDoc 不仅仅是一种轻量级标记语言。它使我们能够并鼓励我们编写可重用、结构化的内容。

分块 可重用的内容可以与其他内容混合搭配，以创建适合设备、上下文或情况的组合。这也是保持内容 DRY（不要重复自己）的一种方式，这样我们就无需在一打甚至两个地方更新相同的内容。

结构化内容是有意义的、语义化的内容，它使用元数据进行标记。如果我们知道文档中有什么，我们就可以对文档做很多事情。我们可以提取一个引语或摘要。我们可以在不需要时隐藏内容。我们可以呈现一个结构并允许用户深入了解他们想要看到的内容。

内容不再“存在于页面上”。发布的未来单位是“块”。这些更小、更独立的数据源可以针对特定平台进行调整，或通过自动化进行聚合。

Web 正在改变。它已经离开了桌面。它现在是一个公路战士。我们思考内容发布的方式也必须随之改变。我们必须将内容与呈现分离，这比以往任何时候都重要。

回顾

编写文档很难。所以我们做的不够。然而，我们却错过了接触和影响目标受众的最佳机会。让我们对此做些什么。

参加更轻松的文档、更简单的网站和更快的协作，学习如何

  • 轻量级标记使编写文档更容易

  • 静态网站生成器和 CSS 框架使网站更简单

  • git 和 GitHub 使协作处理内容和在线发布内容更快

…所有这些都由开源软件驱动

Ruby

Git

AsciiDoc / Asciidoctor

Awestruct

Jekyll

Haml / Slim

SASS / Compass

Zurb Foundation

Travis CI

让我们一起烘焙更好的文档。可重用且结构化的文档。

什么、在哪里和何时？

Title

更轻松的文档、更简单的网站和更快的协作
日期

2013 年 7 月 23 日，星期二
时间

下午 1:30 - 5:00（3 小时 30 分钟）
房间

D139/140，俄勒冈会议中心
类型

研讨会
类别

工具与技术

您可以在官方会议页面上找到有关该研讨会的所有详细信息，包括会议摘要。

谁？

与会者

像您一样热衷于文档和 Web 发布的热情开源社区成员。

不确定是不是您？您是否为以下任何一项做出贡献、维护或组织？

  • 手册、用户指南、教程或 README 文件

  • 新闻、新闻稿或公告

  • 文章或书籍

  • 宣传册或媒体资料包

  • 会议或活动信息

  • 征求建议书（RFP）

  • 简历或个人网站

如果您点了点头，那么您就是我们中的一员 :)

培训师

Dan Allen Dan Allen

Dan 是一位开源倡导者、社区催化剂、作家和演讲者。他自豪地以 Red Hat 员工和社区成员的身份追求这些热情。

作为 Red Hat 的首席软件工程师，他领导 Asciidoctor 项目并担任 Arquillian 的社区经理。他利用这些经验帮助许多开源项目取得巨大成功。除了喝一杯 Trappist 啤酒或享用比利时巧克力之外，他没有什么更愿意做的了。

Sarah White Sarah White

Sarah 担任 Arquillian 和 Asciidoctor 项目的内容策略师——对于一个热衷于开源、外星入侵和写作的人来说，这是一个理想的职位。

如果还有改进的空间，Sarah 会找到它。很多改进空间。

很久以前，在一个不太遥远的星系，她评估了危险废物场地，并追踪了流域的农药路线。所以她对识别和根除导致死亡的事物，包括软件错误和糟糕的文档，略知一二。

先决条件

掌握 HTML 知识和熟悉使用命令行都是必不可少的。掌握一些 git 和 Ruby 知识很有用，但初学者应该能够“在工作中”掌握必要的培训。

  • 笔记本电脑

  • GitHub 账户

  • Ruby 1.9（或 JRuby 1.7）

    • Linux： apt-get install rubygems、yum install rubygems 或同等命令

    • OSX： 默认可用

    • Windows： RubyInstaller

  • Git 客户端

  • 文本编辑器

阅读清单

我们准备了一些阅读材料，可以让您更好地了解本次会议的内容以及您将要学习的内容。这些资源还应该帮助您在研讨会结束后继续学习该主题。

策略
技术

完整资源列表可在研讨会 wiki 的参考资源页面上找到。

期待在 OSCON 见到您！

使用 Asciidoclet 用 AsciiDoc 编写 Javadoc

作者：John Ericksen -

我们很高兴地宣布 Asciidoctor 大家庭的最新成员：Asciidoclet。 Asciidoclet 是一个基于 Asciidoctor 的 Javadoc Doclet，它使开发人员能够使用 AsciiDoc 语法编写 Javadoc 注释。

动机

从一开始，Java 设计者就做得对的一点是，将文档与源代码放在一起。这使得文档能与不断变化的源代码保持更同步，并支持多种查看平台，最值得注意的是 HTML 生成和 IDE 集成。

Javadoc 的主要缺点是需要使用嵌入的 HTML 片段来实现高级（甚至适度）格式化。这就是 AsciiDoc 集成大放异彩的地方。作为一种轻量级标记语言，AsciiDoc 让开发人员能够进行高级格式化，而无需处理低级 HTML 标记。换句话说，开发人员可以专注于内容而不是标记，并仍然获得漂亮的结果。

将 AsciiDoc 与 Javadocs 配对意味着可读的源代码和精美的 Javadocs，两全其美！

用法

一旦 Asciidoclet 被集成到 Javadoc 中，只需在 Javadocs 中使用 AsciiDoc 标记即可。以下示例演示了 Asciidoclet 的多项功能

/**
 * = Asciidoclet (1)
 *
 * Sample comments that include +source code+. (2)
 *
 * [source,java] (3)
 * --
 * public class Asciidoclet extends Doclet {
 *     private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();
 *
 *     @SuppressWarnings("UnusedDeclaration") (4)
 *     public static boolean start(RootDoc rootDoc) {
 *         new Asciidoclet().render(rootDoc);
 *         return Standard.start(rootDoc);
 *     }
 * }
 * --
 *
 * @author https://github.com/johncarl81[John Ericksen] (5)
 */
public class Asciidoclet extends Doclet {
}
1 使用 = 标记即可轻松创建标题。
2 段落是默认的，不需要 <p> html 标签。行内源代码可以用 + 符号包围文本来标记。
3 使用 [source,language] 标签和块分隔符 --（也称为“围栏”）可以轻松标记源代码
4 臭名昭著的 @ 符号由 Asciidoclet 自动处理，避免了标准的 {@literal @} 样板代码。
5 行内 AsciiDoc 标记可用于 Javadoc 标签。此示例重点介绍了链接渲染。

分发

Asciidoclet 已发布到 Maven Central。工件信息汇总在下表中。

Asciidoclet 的工件信息
组 ID 工件 ID 版本 下载

org.asciidoctor

asciidoclet

0.1.3*

pom jar javadoc (jar) source (jar)

* 此版本基于 Asciidoctor 0.1.3 版本。

安装

Asciidoclet 是一个标准的 Javadoc Doclet，可以像这样使用。安装 Asciidoclet 最简单的方法之一是将其作为 Doclet 添加到 maven-javadoc-plugin 中

Maven Doclet 声明
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <doclet>org.asciidoctor.Asciidoclet</doclet>
        <docletArtifact>
           <groupId>org.asciidoctor</groupId>
           <artifactId>asciidoclet</artifactId>
           <version>${asciidoclet.version}</version>
        </docletArtifact>
    </configuration>
</plugin>

我们希望此扩展能帮助您将 Javadocs 推向新的高度。一如既往，我们欢迎协作，您可以在 GitHub 上找到（并 fork）源代码。

非常感谢 Alex Soto（来自 Asciidoctor Java 集成项目）、Jason Porter 和 Dan Allen 的反馈和支持，以及所有为 Asciidoctor 项目做出贡献的人。由于 Asciidoctor 社区的出色工作和协作，编写此扩展变得前所未有的轻松。

asciidoctor.js - 在浏览器中渲染 AsciiDoc！

作者：Dan Allen -

我们结合了 Asciidoctor 和 Opal，将 AsciiDoc 渲染带到浏览器！

简介

Opal

asciidoctor.js 使用 Opal Ruby 到 JavaScript 交叉编译器，生成 Asciidoctor 的直接 JavaScript 端口，Asciidoctor 是 AsciiDoc 的一种实现。结果就是在浏览器中进行 AsciiDoc 渲染！

该项目主要由一个 Rake 构建脚本组成，该脚本在 Asciidoctor 源代码上执行 Opal 编译器，从而生成 asciidoctor.js 脚本。

Opal 解析 Ruby 代码和任何必需的库，然后将代码重写为 Opal 命名空间下的 JavaScript。生成的 JavaScript 可以在任何 JavaScript 运行时环境中执行，例如浏览器或 node.js 应用程序。

验证概念

当我第一次发现 Opal 时，我心想，“是的，这可能可行。”我当时并不知道要实现这个概念验证任务不小。

这项工作包括填补 Opal 的空白，以支持 Asciidoctor 使用的所有 Ruby 标准库功能，以及对 Asciidoctor 进行更改以使其与 JavaScript 施加的限制（如不可变字符串）兼容。

虽然仍有一些不足之处，但我很自豪地说，asciidoctor.js 可以成功渲染完整的 AsciiDoc 用户指南（该文档在 Asciidoctor 开发过程中一直作为合规性基准）。

脚本

Rake 构建生成的两个脚本对于在浏览器中运行 Asciidoctor 是必需的

opal.js

JavaScript 中的 Ruby 运行时

asciidoctor.js

Asciidoctor 的 JavaScript 端口

不用担心这些文件的大小。我们还没有开始优化，只是完成了概念验证。

话虽如此，这两个文件压缩起来效果很好，将 asciidoctor.js 从 500K 多缩小到大约 90K。Opal 有生成更有效率代码的选项，但目前它们会引起问题。一旦我们解决了这些问题，生成的文件大小应该就会变得非常可以接受。

您需要将这两个文件加载到您的 JavaScript 环境中才能使用 Asciidoctor。例如，在一个 HTML 页面中，添加这两个 <script> 标签（最好放在页面底部）

<script src="opal.js"></script>
<script src="asciidoctor.js"></script>

您可以通过运行 README 中描述的示例来查看这些脚本的实际效果（README）。

用法

要与生成的代码交互，您可以

  1. 编写 Ruby 代码，该代码可以挂接到 Opal 编译为 JavaScript 的本机 JavaScript 环境

  2. 直接从 JavaScript 调用 Opal 生成的 JavaScript API

这是一个示例，展示了 Ruby 如何与本机 JavaScript 环境交互以在浏览器中渲染 AsciiDoc 字符串

data = %(= asciidoctor.js - Render AsciiDoc in your browser!
Dan Allen
2013-05-21

We've combined https://asciidoctor.org.cn[Asciidoctor] and
https://opalrb.com[Opal] to bring AsciiDoc rendering to the browser!)

$window.addEventListener 'DOMContentLoaded', proc {
  html_doc = Asciidoctor.render(data, :safe => :safe,
    :attributes => %w(notitle! anchors imagesdir=./images))
  $document.getElementById('content').innerHTML = html_doc
}, false

对 Asciidoctor 的更改

目前，Asciidoctor 需要进行一些更改才能与 Opal 编译。这些更改保存在 Asciidoctor git 存储库的 asciidoctor.js 分支中，asciidoctor.js 就是从此分支编译的。目标是最终消除所有这些差异，以便 Asciidoctor 可以按原样编译为 JavaScript。

开始玩吧！

现在是时候开始玩 asciidoctor.js 了。探索它的功能以及如何改进它。然后，参与 Asciidoctor 或 Opal，帮助使浏览器中的 AsciiDoc 变得最好！

在 Java 中享受 Asciidoctor 的魔力

作者：Alex Soto -

Asciidoctor Java 集成是使用 Asciidoctor 在 Java 中而不是 Ruby 中渲染所有 AsciiDoc 文档的官方方式。

安装

由于 asciidoctor-java-integration 是一个标准的 jar 文件，您应该做的就是将库添加到类路径中。

Maven 中的依赖项声明
<dependencies>
  <dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-java-integration</artifactId>
    <version>${asciidoctor.version}</version>                   (1)
  </dependency>
</dependencies>
1 由于该库跟踪 Asciidoctor 的版本，您可以根据需要使用任何 Asciidoctor 版本。

用法

asciidoctor-java-integration 的核心接口是 Asciidoctor 接口。它提供了两个渲染 asciidoc 内容的方法：render 和 renderFile。两者都返回渲染内容的字符串。

表 1. 方法说明
名称 描述

render

将 AsciiDoc 内容解析为 Document 并将其渲染为指定的后端格式。

renderFile

将 AsciiDoc 文件的内容解析为 Document 并将其渲染为指定的后端格式。

还提供了一个工厂方法来创建 Asciidoctor 接口的实例。

Asciidoctor 接口的创建
import static org.asciidoctor.Asciidoctor.Factory.create;
import org.asciidoctor.Asciidoctor;

Asciidoctor asciidoctor = create();

然后，我们可以根据我们的需求调用 render 方法。

渲染字符串
String rendered = asciidoctor.render("*This* is it.", Collections.EMPTY_MAP);
System.out.println(rendered);

但您也可以渲染文件内容。

渲染文件
String rendered = asciidoctor.renderFile("docs/sample.adoc", Collections.EMPTY_MAP);
System.out.println(rendered);

选项

Asciidoctor 支持不同类型的选项，例如 in_place（在文件中渲染输出）、template_dir（用于提供 Tilt 兼容模板目录以替换默认内置模板），或者例如 attributes 选项（其中我们可以设置将在 asciidoc 文档中使用的属性的键值对）。

render 方法的第二个参数是一个 java.util.Map，我们可以在其中设置所有这些选项。

使用 in_place 选项和 backend 属性的示例
Map<String, Object> attributes = new HashMap<String, Object>();
attributes.put("backend", "docbook");

Map<String, Object> options = new HashMap<String, Object>();
options.put("in_place", true);
options.put("attributes", attributes);

String render = asciidoctor.renderFile("docs/sample.adoc", options);

在之前的例子中，我们创建了一个Map，其中我们放入了将输入渲染为docbook并生成输出文件所需的选项和属性（也创建了一个Map）。

但是 asciidoctor-java-integration 还提供了两个构建器类，以便更具可读性的方式创建这些Map。

AttributesBuilder 用于创建设置了所需属性的Map，而 OptionsBuilder 可用于设置选项。使用这些类重写的上一个示例如下所示：

设置属性和选项的示例
import static org.asciidoctor.AttributesBuilder.attributes;
import static org.asciidoctor.OptionsBuilder.options;

...

Map<String, Object> attributes = attributes().backend("docbook").asMap();
Map<String, Object> options = options().inPlace(true).attributes(attributes).asMap();

String render = asciidoctor.renderFile("docs/sample.adoc", options);

实用工具

提供了一个实用类，用于搜索根文件夹及其所有子文件夹中存在的所有asciidoc文件。实际上，它会查找所有以 .asc、.asciidoc、.ad 或 .adoc 结尾的文件。这个类是 AsciidocDirectoryWalker。

查找所有asciidoc文件的示例
DirectoryWalker directoryWalker = new AsciidocDirectoryWalker("docs");
List<File> asciidocFiles = directoryWalker.scan();

贡献

您可以通过补丁、更好的文档、功能请求，以及您能提供的任何帮助来贡献。

  • 1 of 2