Asciidoctor Java集成是官方使用Asciidoctor通过Java而不是Ruby来渲染所有http://asciidoc.org[AsciiDoc]文档的手段。

安装

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

Maven中的依赖声明

xml <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。这两个方法都返回一个包含渲染内容的字符串。

Table 1. 方法描述
名称 描述

render

将AsciiDoc内容解析成一个文档，并渲染成指定的后端格式。

renderFile

将AsciiDoc文件的内容解析成一个文档，并渲染成指定的后端格式。

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

创建Asciidoctor接口

java import static org.asciidoctor.Asciidoctor.Factory.create; import org.asciidoctor.Asciidoctor;

Asciidoctor asciidoctor = create();

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

渲染字符串

java String rendered = asciidoctor.render("This is it.", Collections.EMPTY_MAP); System.out.println(rendered);

但你也可以渲染文件的内容。

渲染文件

java 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属性的示例

java 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，在这个Map中，我们放入了渲染输入为docbook所需的选项和属性（同时创建了一个Map）以及生成一个输出文件。

但是 asciidoctor-java-integration 也提供了两个构建器类以更易读的形式创建这些映射。

AttributesBuilder 用于创建一个设置了必需属性的映射，而 OptionsBuilder 可用于选项。使用这些类的前面示例看起来像这样：

示例设置属性和选项

java 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的示例

java DirectoryWalker directoryWalker = new AsciidocDirectoryWalker("docs"); List<File> asciidocFiles = directoryWalker.scan();

贡献

你可以通过贡献补丁(patch)、改进文档、提出功能需求、提供任何你能提供的帮助来做出贡献。