Asciidoctor Maven插件使用

在项目应用中，我们会写很多文档去传递我们的设计思想、开发经验、采坑经历等等。使用Asciidoc的格式对非技术人员就不是那么的友好，或者说传递性、通用性与PDF和网页相比就差很多了。在JVM项目中可以使用Maven的插件方式将.adoc文件格式转化为PDF、HTML、EPUB等文件格式。

快速入门

工程结构

|doc-demo
|-src
|--main
|---asciidoc
|----.adoc文件
|---resources
|----images
|pom.xml

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.demo</groupId>
    <artifactId>docs</artifactId>
    <version>1.1.0-SNAPSHOT</version>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <asciidoctorj.version>1.5.6</asciidoctorj.version>
        <asciidoctorj.diagram.version>1.5.4.1</asciidoctorj.diagram.version>
        <jruby.version>1.7.26</jruby.version>
    </properties>
    <build>
        <!-- 默认命令，配置后可以直接使用mvn编译 -->
        <defaultGoal>process-resources</defaultGoal>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <targetPath>${project.build.directory}/book</targetPath>
            </resource>
        </resources>
        <plugins>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.5</version>
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <sourceHighlighter>prettify</sourceHighlighter>
                            <attributes>
                                <toc>left</toc>
                                <icons>font</icons>
                                <sectanchors>true</sectanchors>
                                <!-- set the idprefix to blank -->
                                <idprefix/>
                            </attributes>
                        </configuration>
                    </execution>
                </executions>
                <dependencies>
                    <!-- Comment this section to use the default jruby artifact provided by the plugin -->
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>${jruby.version}</version>
                    </dependency>
                    <!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj</artifactId>
                        <version>${asciidoctorj.version}</version>
                    </dependency>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-diagram</artifactId>
                        <version>${asciidoctorj.diagram.version}</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <outputDirectory>${project.build.directory}/book</outputDirectory>
                    <sourceDocumentName>book.adoc</sourceDocumentName>
                    <imagesDir>./</imagesDir>
                    <preserveDirectories>false</preserveDirectories>
                    <requires>
                        <require>asciidoctor-diagram</require>
                    </requires>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

执行mvn命令

mvn clean process-asciidoc

生成的HTML可以使用Http Server或者Nginx等服务进行部署，甚至可以使用Jenkins进行自动化部署。

生成PDF

工程结构

|doc-demo
|-src
|--main
|---asciidoc
|----data
|-----fonts
|-----themes
|----.adoc文件
|---resources
|----images
|pom.xml

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.tairanchina.csp.dmp</groupId>
    <artifactId>docs</artifactId>
    <version>1.1.0-SNAPSHOT</version>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <asciidoctorj.version>1.5.6</asciidoctorj.version>
        <asciidoctorj.diagram.version>1.5.4.1</asciidoctorj.diagram.version>
        <jruby.version>1.7.26</jruby.version>
        <asciidoctorj.pdf.version>1.5.0-alpha-zh.16</asciidoctorj.pdf.version>
    </properties>
    <build>
        <!--https://github.com/asciidoctor/asciidoctor-maven-examples-->
        <!--https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/master/README_zh-CN.adoc-->
        <!-- 默认命令，配置后可以直接使用mvn编译 -->
        <defaultGoal>process-resources</defaultGoal>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <targetPath>${project.build.directory}/book</targetPath>
            </resource>
        </resources>
        <plugins>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.5</version>
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <sourceHighlighter>prettify</sourceHighlighter>
                            <attributes>
                                <toc>left</toc>
                                <icons>font</icons>
                                <sectanchors>true</sectanchors>
                                <!-- set the idprefix to blank -->
                                <idprefix/>
                            </attributes>
                        </configuration>
                    </execution>

                    <execution>
                        <id>output-pdf</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <sourceHighlighter>coderay</sourceHighlighter>
                            <doctype>book</doctype>
                            <attributes>
                                <icons>font</icons>
                                <pagenums/>
                                <toc/>
                                <idprefix/>
                                <idseparator>-</idseparator>
                                <pdf-fontsdir>data/fonts</pdf-fontsdir>
                                <pdf-stylesdir>data/themes</pdf-stylesdir>
                                <pdf-style>cn</pdf-style>
                            </attributes>
                        </configuration>
                    </execution>
                </executions>
                <dependencies>
                    <!-- Comment this section to use the default jruby artifact provided by the plugin -->
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>${jruby.version}</version>
                    </dependency>
                    <!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj</artifactId>
                        <version>${asciidoctorj.version}</version>
                    </dependency>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-diagram</artifactId>
                        <version>${asciidoctorj.diagram.version}</version>
                    </dependency>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>${asciidoctorj.pdf.version}</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <outputDirectory>${project.build.directory}/book</outputDirectory>
                    <sourceDocumentName>book.adoc</sourceDocumentName>
                    <imagesDir>./</imagesDir>
                    <preserveDirectories>false</preserveDirectories>
                    <requires>
                        <require>asciidoctor-diagram</require>
                    </requires>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

执行mvn命令

mvn clean process-asciidoc

由于PDF格式插件没有安装中文字体，生成的PDF格式上会存在缺失，上方的fonts和themes可以对PDF的生成格式进行自定义，有时候为了方便，可以将其与 asciidoctorj-pdf源码进行合并，手动打一个依赖包，放到自己的私服仓库中。

常见问题

• 在生成PDF的时候，可能code部分会存在很多空格的问题，一般产生这样的问题不是字体问题，而是编写格式有问题，可以选择将``符号去掉。

参考资料

Example

Asciidoctor插件中文文档

Asciidoctor-PDF

中文乱码问题解决方案