AsciidoctorJ 1.6.0 发布，终于来了！

作者 Robert Panzer, Dan Allen 和 Sarah White - 2019年1月2日，星期三

经过数年的酝酿（或者说是桶陈？），我们终于发布了 AsciidoctorJ 1.6.0！相关构件可从 Bintray 和 Maven Central 获取。

AsciidoctorJ 是什么？

AsciidoctorJ 是在 JVM 上运行 Asciidoctor 的官方库。使用 AsciidoctorJ，您可以转换 AsciiDoc 内容，分析已解析的 AsciiDoc 文档的结构，并用 Java 和其他 JVM 语言编写 Asciidoctor 扩展。

在升级之前，您需要了解一些重要的事情，本文将对此进行介绍。虽然 AsciidoctorJ 仍然建立在强大的 Asciidoctor RubyGem 的基础上，但它已经发展成为一个独立的を有份的项目。此次发布为新老用户带来了稳定性和关键增强。请举杯，我们将为您带来所有细节。

迈向 SemVer 的重要里程碑

尽管版本号如此，这次发布应被视为一次重大发布。因此，它与 1.5.x 系列的发布不兼容。

AsciidoctorJ 1.6.0 是为了准备切换到语义化版本控制 (SemVer) 而进行的最后一次过渡性发布。我们将最后一次打破规则，但有充分的理由。考虑到 1.6.0 分支已经桶陈了很长时间，我们希望允许其被启用以收集反馈，并挖掘出意外的惊喜，然后再跳到 2.0.0 和 SemVer。如果一切顺利，我们预计 2.0.0 版本将在该版本之后不久发布。届时，我们将开始按照 SemVer 规则对 AsciidoctorJ 进行版本控制。

要了解更多关于 SemVer 以及它如何影响 Asciidoctor 项目的总体情况，请参阅切换到语义化版本控制。

切换到 SemVer 也意味着 AsciidoctorJ 将独立于 Asciidoctor 进行版本控制。AsciidoctorJ 已经发展成为不仅仅是为 JVM 打包的 Asciidoctor RubyGem。它拥有完整的 API，包括基于 Java 的扩展以及与 Java 生态系统的紧密集成（例如，JUL、Ruby 对象桥接等）。其独立的版本线将允许它更快地发展，并帮助大家更好地理解每个版本将带来什么。最重要的是，它将解决导致 1.6.0 版本积压多年的情况。

新功能

主要的 API 和打包更改: 自 AsciidoctorJ 诞生以来，我们对 JRuby 以及它如何桥接 Ruby 和 Java 对象有了很多了解。利用这些知识，我们彻底重新设计了底层集成，以解决原始设计中的不足。

这种重新设计需要我们对 API 进行破坏性更改，这对于 AsciidoctorJ 的持续发展是绝对必要的。但这同时也为我们提供了修复众多 Bug 的机会，而这些 Bug 在 1.5.x 系列中无法在不破坏兼容性的情况下修复。您会很高兴地得知，重新设计消除了在编写扩展或使用 1.5.x 版本导航文档模型时可能遇到的故障。

作为此更改的一部分，我们将 API 和实现类拆分为单独的包和 JAR，以对其进行适当的隔离。我们还通过映射 Asciidoctor 中的所有节点类型并移除 ContentPart 和 StructuredDocument API 来协调相互冲突的文档模型。请参阅 API 文档（api，impl）以了解可用的类型及其组织方式。
重构的扩展 API: 得益于重新设计，基于 JRuby 的实现被更好地隐藏在 API 之后。特别是，API 中不再有 JRuby 的 RubyObject 类的引用。

抽象语法树 (AST) 的接口已完全重命名，以更好地表示其目的。例如，AbstractNode 接口已重命名为 ContentNode，AbstractBlock 已重命名为 StructuralNode，Inline 已重命名为 PhraseNode。Java 中映射了更多的 AST，包括列表和定义列表，以及用于在扩展处理器中创建表结构的辅助工具。

总的来说，扩展和 AST 的 API 应该感觉像是一个纯粹的 Java 库（例如，getAttr() 现在是 getAttribute()）。您甚至可以使用基于注释的配置（例如，@Name）来定义扩展处理器。

请查阅集成器指南，了解所有相关信息并找到许多示例。
添加了转换器 API: 引入了一个新的转换器 API，使得完全用 Java 实现自定义输出格式的转换器成为可能。此 API 允许您从 Java 扩展 Asciidoctor，类似于您已经通过扩展 API 所能做到的。您可以按照转换器文档来了解如何使用这个新 API。

事实上，已经有一个转换器使用此 API 从 Groovy 将 AsciiDoc 转换为 Leanpub 风格的 Markdown。
访问 Asciidoctor 的日志: 当 Asciidoctor 在文档中遇到问题时，它会将错误和警告消息记录到 Ruby 日志记录器。将 Asciidoctor 集成到您自己的软件中时，捕获这些日志消息以便妥善处理非常重要。以前，这些消息是 AsciidoctorJ 无法触及的。现在情况已不再如此。新的日志处理 API 会捕获 Asciidoctor 中记录的消息，并将它们路由到您自己的日志处理程序。
更好的文档: AsciidoctorJ 1.6.0 提供了扩展和经过测试的文档，用于编写扩展和转换器。这些文档保证是正确的，因为它们会与每次提交一起测试 ;) 并且正在将文档整合到 Asciidoctor 的新 Antora 文档站点中。

有关此版本中发生的更改的更详细说明，请参阅发布说明。请记住，由于 1.6.0 的开发与 1.5.x 并行了很长时间，因此 1.6.0 中的许多更改可能对您来说已经很熟悉了，因为它们已被反向移植到 1.5.x 发布系列中。

迁移说明

如果您只使用 Asciidoctor、Asciidoctor.Factory 和 *Builder 类（例如，Asciidoctor#convertFile），您可能无需更改代码。事实上，Asciidoctor Maven Plugin 和 Asciidoctor Gradle Plugin 已经支持此版本，主要是因为它们只依赖于公共的加载/转换 API。

AST 和扩展 API 的必要更改确实引入了破坏性更改，需要修改您现有的扩展。迁移扩展主要是为了符合新的 API。这主要包括切换 AST 接口的新名称，并与更新的方法签名保持一致。除了名称和签名更改之外，API 仍然应该是可识别的，因此与您现有的逻辑兼容。

以下是为 AsciidoctorJ 1.5.8 和 1.6.0 编写的几个扩展示例，以让您了解需要注意的更改类型：

YellBlock - 1.5.8 vs 1.6.0
ArrowsAndBoxesBlock - 1.5.8 vs 1.6.0
ManpageMacro - 1.5.8 vs 1.6.0

如果您在迁移扩展或文档内省代码时遇到困难，请在问题跟踪器中提交问题，以便我们找到前进的道路。

Java 兼容性

Asciidoctor 1.6.0 最低需要 Java 8。它也能在 Java 11 上运行，并且已针对 Java 11 进行测试。

从 AsciidoctorJ 1.6.0 开始，该项目将遵循 Oracle 官方 Java SE 支持路线图来确定其 Java 兼容性。虽然 AsciidoctorJ 不需要 Oracle Java SE，但该路线图可以作为判断哪些 Java 版本被认为是当前的有用参考。

Asciidoctor 1.6.0 尚不支持在模块路径上运行，这是 Java 9 中引入的 Java 平台模块系统的一个关键特性。我们希望在即将发布的版本中实现这一点。然而，这将取决于 AsciidoctorJ 的依赖项（最重要的是 JRuby）在这方面的进展。尽管有此限制，您仍然可以在 Java 11 上运行 Asciidoctor 1.6.0。

致谢

我们想借此机会表彰几位关键人物，他们共同促成了这次发布的成功。

Jérémie Bresson，他发起将 API 和实现类分离，并现代化了 API 签名。
Abel Romero，他协助设计了 JUL 日志集成，并首先在 Maven 插件中进行了测试。
Frank Becker，他彻底改进和简化了 Gradle 构建。
Guillaume Grossetie，他对 API 和实现进行了大量清理和改进，并通过启动 AsciidoctorG 对重新设计进行了压力测试。
Charles Nutter、Thomas Enebo 以及 JRuby 团队，他们创建和维护了 AsciidoctorJ 所基于的 JRuby。
最后，我们的“前辈” Alex Soto，他启动了 AsciidoctorJ 项目，并向我们展示了其潜在的可能性。

当然，还有许多其他人值得感谢。正如我们多次说过的，没有众多志愿者的辛勤工作和协作，这个项目是不可能实现的。所以，谢谢您！

2.0.0 的展望

破坏性更改尚未结束。在走向 2.0.0 的过程中，我们希望进一步拆分 AsciidoctorJ 的 API 和其实现。我们的主要目标是支持底层的替代实现，例如 Asciidoctor.js，使用相同的公共 API。

为了帮助我们达到 2.0.0，我们恳请您测试 1.6.0 版本，并告知我们您是否遇到任何问题或更改，这些更改妨碍您迁移到它。现在是时候在 2.0.0 版本发布之前将其做好。请在问题跟踪器中报告您发现的所有问题。

感谢您陪伴我们一起将 AsciiDoc 的精华带到 JVM。

切换到语义化版本控制

作者 Dan Allen - 2018年12月31日，星期一

经过多年的讨论，我们终于准备好在 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 规则进行版本控制。

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

作者：Maxime Gréau - 2015 年 3 月 4 日，星期三

我们很高兴地宣布 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 测试。我们将讨论

docker-asciidoctorj，这是 Asciidoctor 的专用 GitHub 项目
Docker Hub 上的官方 Asciidoctor 组织
Arquillian Cube，它是 Arquillian 扩展，可用于从 Arquillian 管理 Docker 容器
JBoss 的 WildFly Docker 镜像

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

AsciidoctorJ 1.5.0 发布！

作者 Alex Soto - 2014 年 8 月 21 日，星期四

我们很高兴地将 Asciidoctor 的最新里程碑 Asciidoctor 1.5.0，以 AsciidoctorJ 1.5.0 的形式带到 JVM！

AsciidoctorJ 是什么？

AsciidoctorJ 是在 JVM 上使用 Asciidoctor 的官方库。借助 AsciidoctorJ，您可以使用 Java 和其他 JVM 语言转换 AsciiDoc 内容或分析已解析的 AsciiDoc 文档的结构。

已解决的问题

以下问题已在 1.5.0 版本中解决：

添加了向 AsciidoctorJ 注册扩展的方法，这些扩展可以用 Ruby 或 Java 编写。解决了 #90 和 #157。
创建了一个 SPI，以便通过将 jar 添加到 classpath 中来自动注册 Java 扩展。解决了 #97
Extension API 已更新，以反映 Asciidoctor 1.5.0 中所做的修改。解决了 #113、#114、#148、#162 和 #166。
提供了一个方法来注销之前注册的任何扩展。解决了 #122
向 CLI 类添加了 -r 和 -I 标志，分别用于要求额外的 Ruby 脚本和追加到加载路径。解决了 #171。
向 CLI 类添加了 -V 和 --version 标志。解决了 #87 和 #117。
添加了与 Asciidoctor EPUB3 项目的集成。您可以将 epub3 设置为后端。解决了 #168 和 #179
使用 findBy 方法更新了 AbstractBlock 类。解决了 #164
更新了 Document 类以与 Asciidoctor::Document 对齐，因此获取标题可以返回一个 Title 类（包含标题、副标题），而不是一个包含完整标题的字符串。解决了 #167
推广了属性 sectnumlevels、hardbreaks、appendix-caption、stem、hide-uri-schema、nofooter、source-language 和 compat-mode。解决了 #91、#92、#94、#105、#121、#129、#144 和 #163。
您可以从 JRubyRuntimeContext 类中获取 AsciidoctorJ 中使用的 Ruby 实例。解决了 #93
修复了 Ruby 实例和 Attributes 类的一个 bug，该 bug 阻止了 Gradle 插件正常工作。解决了 #96
在 AsciiDocDirectoryWalker 中跳过以“_”（下划线）开头的文件和目录。解决了 #124
将 slf4j 添加为日志系统。解决了 #126
修复了 base_dir 和 Ruby 环境的一个 bug。解决了 #135
Document 对象（如 Section、Block、Node、Document 等）已移至 org.asciidoctor.dom 包。
将 Java 版本更新为 Java 7。解决了 #176

有关此版本中修复的问题的更多信息，请参阅问题跟踪器中的 1.5.0 里程碑！

迁移

从 1.5.0 版本开始，artifactId 已从 asciidoctor-java-integration 更改为 asciidoctorj。您现在应该在项目的 pom.xml 文件中使用以下依赖项声明：

<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj</artifactId>
    <version>1.5.0</version>
</dependency>

升级到 Asciidoctor 1.5.0 时，请参考迁移指南了解迁移内容的详细信息。我们也鼓励您浏览 Asciidoctor 1.5.0 的发行说明。

Asciidoctor 1.5.0 在内部和公共 API 方面都引入了许多更改。例如，扩展 API 已以非微小的方式进行了修改，因此在升级到此版本的 AsciidoctorJ 时，您可能需要将扩展更新到新 API。

访问更新的 AsciidoctorJ 手册，了解如何安装和使用 AsciidoctorJ。

此版本为 Gradle 插件、Maven 插件和 Asciidoclet 的新版本让路，这些插件都基于 AsciidoctorJ。请期待后续的公告！

1 / 1