Introduction to Asciidoctor in Java – Java中Asciidoctor的介绍

最后修改: 2017年 6月 27日

中文/混合/英文(键盘快捷键：t)

1. Introduction

1.介绍

In this article, we’ll make a quick introduction on how to use Asciidoctor with Java. We’ll demonstrate how to generate HTML5 or PDF from an AsciiDoc document.

在这篇文章中，我们将快速介绍如何用Java使用Asciidoctor。我们将演示如何从AsciiDoc文档生成HTML5或PDF。

2. What Is AsciiDoc?

2.什么是AsciiDoc??

AsciiDoc is a text document format. It can be used for writing documentation, books, web pages, man pages and many other.

AsciiDoc是一种文本文档格式。它可用于编写文档、书籍、网页、手册页和许多其他。

Since it’s very configurable, AsciiDoc documents can be converted into many other formats like HTML, PDF, man pages, EPUB, and others.

由于AsciiDoc的可配置性很强，所以它可以被转换成许多其他格式，如HTML、PDF、man page、EPUB等。

Because AsciiDoc syntax is quite basic, it has become very popular with a large support in various browser plugins, plugins for programming languages and other tools.

由于AsciiDoc的语法相当基本，它已经变得非常流行，在各种浏览器插件、编程语言插件和其他工具中得到大量支持。

To learn more about the tool, we suggest reading the official documentation where you can find many useful resources for learning proper syntax and methods for exporting your AsciiDoc document to other formats.

要了解有关该工具的更多信息，我们建议阅读官方文档，在那里你可以找到许多有用的资源来学习正确的语法和将AsciiDoc文档导出为其他格式的方法。

3. What Is Asciidoctor?

3.什么是Asciidoctor？

Asciidoctor is a text processor for converting AsciiDoc documents into HTML, PDF and other formats. It’s written in Ruby and packaged as a RubyGem.

Asciidoctor是一个文本处理器，用于将AsciiDoc文档转换为HTML、PDF和其他格式。它是用Ruby编写的，并被打包成RubyGem。

As mentioned above, AsciiDoc is a very popular format for writing documentation, so you can easily find Asciidoctor as a standard package in many GNU Linux distribution like Ubuntu, Debian, Fedora, and Arch.

如上所述，AsciiDoc是一种非常流行的编写文档的格式，所以你可以很容易地在许多GNU Linux发行版中找到Asciidoctor的标准包，如Ubuntu、Debian、Fedora和Arch。

Since we want to use Asciidoctor on the JVM, we’ll talk about AsciidoctorJ – which is Asciidoctor with Java.

由于我们想在JVM上使用Asciidoctor，我们将讨论AsciidoctorJ–也就是Asciidoctor与Java。

4. Dependencies

4.依赖性

To include AsciidoctorJ package in our application, the following pom.xml entry is needed:

为了在我们的应用程序中包含AsciidoctorJ包，需要以下pom.xml条目。

<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj</artifactId>
    <version>1.5.5</version>
</dependency>
<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj-pdf</artifactId>
    <version>1.5.0-alpha.15</version>
</dependency>

Latest versions of libraries can be found here and here.

最新版本的库可以在这里和这里找到。

5. AsciidoctorJ API

5.AsciidoctorJ的API

The entry point for AsciidoctorJ is the Asciidoctor Java interface.

AsciidoctorJ的入口是AsciidoctorJava接口。

Those methods are:

这些方法是。

  • convert – parses AsciiDoc document from a String or Stream and converts it to the provided format type
  • convertFile – parses AsciiDoc document from a provided File object and converts it to the provided format type
  • convertFiles – same as previous, but method accepts multiple File objects
  • convertDirectory – parses all AsciiDoc documents in provided folder and converts them to the provided format type

5.1. API Usage in Code

5.1.代码中的API用法

To create an Asciidoctor instance, you need to retrieve the instance from the provided factory method:

要创建一个Asciidoctor实例，你需要从提供的工厂方法中检索实例。

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

With retrieved instance, we can convert AsciiDoc document very easily:

通过检索的实例，我们可以非常容易地转换AsciiDoc文档。

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

If we want to convert a text document from the file system, we’ll use the convertFile method:

如果我们想从文件系统中转换一个文本文档，我们将使用convertFile方法。

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

For converting multiple files, the convertFiles method accepts List object as a first parameter and returns arrays of String objects.
More interesting is how to convert a whole directory with AsciidoctorJ.

对于转换多个文件，convertFiles方法接受List对象作为第一个参数并返回String对象的数组。
更有趣的是如何用AsciidoctorJ转换整个目录。

As mentioned above, to convert a whole directory – we should call the convertDirectory method. This scans the provided path and searches for all files with AsciiDoc extensions (.adoc, .ad, .asciidoc, .asc) and converts them. To scan all files, an instance of the DirectoryWalker should be provided to the method.

如上所述，要转换整个目录 – 我们应该调用convertDirectory方法。这个方法扫描所提供的路径，搜索所有以AsciiDoc为扩展名的文件（.adoc, .ad, .asciidoc, .asc）并转换它们。为了扫描所有文件，应该向该方法提供一个DirectoryWalker的实例。

Currently, Asciidoctor provides two built-in implementations of mentioned interface:

目前，Asciidoctor提供了上述接口的两个内置实现。

  • AsciiDocDirectoryWalker – converts all files of given folder and its subfolders. Ignores all files starting with “_”
  • GlobDirectoryWalker – convert all files of given folder following a glob expression
String[] result = asciidoctor.convertDirectory(
  new AsciiDocDirectoryWalker("src/asciidoc"),
  new HashMap<String, Object>());

Also, we can call convert method with provided java.io.Reader and java.io.Writer interfaces. Reader interface is used as the source, and Writer interface is used for writing converted data:

另外，我们可以用提供的java.io.Reader和java.io.Writer接口来调用转换方法。 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 Generation

5.2.PDF生成

To generate a PDF file from an Asciidoc document, we need to specify the type of the generated file in options. If you look a little more carefully into the previous examples, you’ll notice that second parameter of any convert method is a Map – which represents options object.

为了从Asciidoc文档中生成一个PDF文件，我们需要在选项中指定生成文件的类型。如果你更仔细地看一下前面的例子，你会发现任何转换方法的第二个参数是一个Map–它代表选项对象。

We’ll set the in_place option to true so that our file is automatically generated and saved to the file system:

我们将设置in_place选项为true，这样我们的文件就会自动生成并保存在文件系统中。

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

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

6. Maven Plugin

6.Maven Plugin

In the previous section, we showed how we can generate PDF file directly with your own implementation in Java. In this section, we will show how you to generate PDF file during Maven build. Simiar plugins exist for Gradle and Ant.

在上一节中，我们展示了如何用你自己的Java实现直接生成PDF文件。在本节中，我们将展示如何在Maven构建过程中生成PDF文件。Gradle和Ant都有Simiar插件，。

To enable PDF generation during the build, you need to add this dependency to your pom.xml:

要在构建过程中启用PDF生成，你需要在你的pom.xml中添加这个依赖项：。

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.5</version>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>1.5.0-alpha.15</version>
        </dependency>
    </dependencies>
</plugin>

The latest version of Maven plugin dependency can be found here.

最新版本的Maven插件依赖性可以在这里找到。

6.1. Usage

6.1.使用方法

To use the plugin in the build, you have to define it in the pom.xml:

要在构建中使用该插件，你必须在pom.xml中定义它：。

<plugin>
    <executions>
        <execution>
            <id>output-html</id> 
            <phase>generate-resources</phase> 
            <goals>
                <goal>process-asciidoc</goal> 
            </goals>
        </execution>
    </executions>
</plugin>

Since the plugin doesn’t run in any specific phase, you have to set the phase where you want to start it.

由于该插件不在任何特定阶段运行，你必须设置你想启动它的阶段。

As with the Asciidoctorj plugin, we can use various options for PDF generation here as well.

与Asciidoctorj插件一样，我们在这里也可以使用各种选项来生成PDF。

Let’s have a quick look at the basic options while you can find other options in the documentation:

让我们快速浏览一下基本选项，而你可以在文档中找到其他选项。

  • sourceDirectory – the location of directory where you have Asciidoc documents
  • outputDirectory – the location of the directory where you want to store generated PDF files
  • backend – the type of the output from Asciidoctor. For PDF generation set for pdf

This is an example how to define basic options in the plugin:

这是一个如何在插件中定义基本选项的例子。

<plugin>
    <configuration>
        <sourceDirectory>src/main/doc</sourceDirectory>
        <outputDirectory>target/docs</outputDirectory>
        <backend>pdf</backend>
    </configuration>
</plugin>

After running the build, the PDF files can be found in the specified output directory.

运行构建后，可以在指定的输出目录中找到PDF文件。

7. Conclusion

7.结论

Even though AsciiDoc is very easy to use and understand, it’s a very powerful tool for managing documentation and other documents.

尽管AsciiDoc非常容易使用和理解，但它是一个非常强大的管理文档和其他文件的工具。

In this article, we demonstrated a simple way to generate HTML and PDF files from AsciiDoc document.

在这篇文章中，我们演示了从AsciiDoc文档生成HTML和PDF文件的简单方法。

The code can be found on over on GitHub.

该代码可以在GitHub上找到。