Asciidoctor 在 Java 中的应用指南

1. 简介

本文将快速介绍如何在 Java 中使用 Asciidoctor，演示如何从 AsciiDoc 文档生成 HTML5 或 PDF 文件。简单来说，Asciidoctor 是个强大的文档处理工具，但很多 Java 开发者对它的集成方式并不熟悉，这里我们直接上干货。

2. 什么是 AsciiDoc？

AsciiDoc 是一种轻量级标记语言，主要用于：

编写技术文档
撰写书籍
生成网页
制作 man 手册页

✅ 它的优势在于：

高度可配置
支持导出多种格式（HTML、PDF、EPUB 等）
语法简单直观，社区支持广泛

⚠️ 避免踩坑：不要把 AsciiDoc 和 Markdown 混淆——虽然两者都是标记语言，但 AsciiDoc 在复杂文档处理上更专业。想深入学习？直接看官方文档，里面有完整的语法说明和导出指南。

3. 什么是 Asciidoctor？

Asciidoctor 是一个文本处理器，核心功能是将 AsciiDoc 文档转换为：

HTML
PDF
其他格式（如 man 页面）

它是基于 Ruby 开发的 Gem 包，在主流 Linux 发行版（Ubuntu、Debian、Fedora 等）中通常默认预装。而我们要用的是 AsciidoctorJ——也就是专门为 Java 平台打造的版本。

4. 依赖配置

在 Java 项目中集成 AsciidoctorJ，只需在 pom.xml 添加这两个依赖：

<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj</artifactId>
    <version>2.5.7</version>
</dependency>
<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj-pdf</artifactId>
    <version>2.3.4</version>
</dependency>

📌 最新版本可在此查询：

5. AsciidoctorJ API 核心功能

AsciidoctorJ 的入口是 Asciidoctor 接口，核心方法包括：

convert：从字符串或流解析并转换文档
convertFile：从文件对象转换文档
convertFiles：批量转换多个文件
convertDirectory：转换整个目录的文档

5.1. API 代码实战

获取 Asciidoctor 实例很简单：

import static org.asciidoctor.Asciidoctor.Factory.create;
import org.asciidoctor.Asciidoctor;
// ...
Asciidoctor asciidoctor = create();

转换字符串示例：

String output = asciidoctor
  .convert("Hello _Baeldung_!", new HashMap<String, Object>());

转换文件示例：

String output = asciidoctor
  .convertFile(new File("baeldung.adoc"), new HashMap<String, Object>());

批量转换目录：直接用 AsciiDocDirectoryWalker 扫描目录（自动识别 .adoc、.ad 等扩展名）：

String[] result = asciidoctor.convertDirectory(
  new AsciiDocDirectoryWalker("src/asciidoc"),
  new HashMap<String, Object>());

💡 高级技巧：使用 Reader 和 Writer 进行流式处理

FileReader reader = new FileReader(new File("sample.adoc"));
StringWriter writer = new StringWriter();
 
asciidoctor.convert(reader, writer, options().asMap());
 
StringBuffer htmlBuffer = writer.getBuffer();

5.2. PDF 生成

生成 PDF 的关键是在选项中指定 backend 为 "pdf"。踩坑提醒：必须设置 inPlace(true) 才能自动保存文件！

Map<String, Object> options = options()
  .inPlace(true)    // 自动保存到文件系统
  .backend("pdf")   // 指定输出格式
  .asMap();

String outfile = asciidoctor.convertFile(new File("baeldung.adoc"), options);

6. Maven 插件集成

除了 Java API，更推荐在构建阶段直接生成文档（Gradle/Ant 也有类似插件）。

6.1. 插件配置

在 pom.xml 添加插件：

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>2.2.2</version>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>2.3.4</version>
        </dependency>
    </dependencies>
    <executions>
        <execution>
            <id>output-html</id> 
            <phase>generate-resources</phase> 
            <goals>
                <goal>process-asciidoc</goal> 
            </goals>
        </execution>
    </executions>
    <configuration>
        <sourceDirectory>src/main/doc</sourceDirectory>
        <outputDirectory>target/docs</outputDirectory>
        <backend>pdf</backend>
    </configuration>
</plugin>

📌 关键配置说明：

sourceDirectory：AsciiDoc 源文件目录
outputDirectory：PDF 输出目录
backend：输出格式（设为 pdf）
phase：绑定到 Maven 生命周期阶段（如 generate-resources）

执行 mvn install 后，PDF 文件会自动生成到 target/docs。

7. 总结

AsciiDoc 看似简单，实则是个文档处理利器——尤其适合需要多格式输出的场景。本文展示了两种 Java 集成方式：

编程式 API（灵活控制转换过程）
Maven 插件（构建自动化）

完整代码示例已上传至 GitHub，建议直接克隆运行体验。

Persistence

REST

Security