基于Asciidoctor生成HTML文档

1、pom文件引入

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

2、方法介绍

基本方法是以下4个：

convert：转成String
convertFile：单个文件转换
convertFiles：批量文件转换
convertDirectory：文件夹下文件

3、代码展示

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

//创建Asciidoctor
Asciidoctor asciidoctor = create();

//生成AsciiDoc String
String html = asciidoctor.convert(
		"Writing AsciiDoc is _easy_!",
	 	new HashMap<String, Object>());
System.out.println(html);

//生成html文件
String html = asciidoctor.convertFile(
		new File("sample.adoc"),
		new HashMap<String, Object>());
System.out.println(html);

//批量文件转换
String[] result = asciidoctor.convertFiles(
    Arrays.asList(new File("sample.adoc")),
    new HashMap<String, Object>());

for (String html : result) {
    System.out.println(html);
}

//文件夹下文件转换
String[] result = asciidoctor.convertDirectory(
    new AsciiDocDirectoryWalker("src/asciidoc"),
    new HashMap<String, Object>());

for (String html : result) {
    System.out.println(html);
}

4、拓展

基于Swagger生成文档需要拓展一些样式和参数：

/**
 * 可选builder
 * @param optionsBuilder
 */
private static void setOptionsOnBuilder(OptionsBuilder optionsBuilder) {
    optionsBuilder
            .backend("html")//生成HTML
            .safe(SafeMode.UNSAFE)
            .headerFooter(true)
            .mkDirs(true)
            .docType("book")
            .toDir(new File(SysConstant.OUTPUT_HTML_DIR))//输出路径
            .destinationDir(new File(SysConstant.OUTPUT_HTML_DIR));//目标路径
}

/**
 * 可选属性
 * @param attributesBuilder
 */
private static void setAttributesOnBuilder(AttributesBuilder attributesBuilder) {
    attributesBuilder.sourceHighlighter("coderay")
            .imagesDir("images@")
            .attributeMissing("skip")
            .attributeUndefined("drop-line");
}

此时，生成的文档已经基本完成，但是没有左侧菜单。如果需要左侧菜单，则需要添加一些属性信息

//文档属性
private static Map<String, Object> attributes = new HashMap<String, Object>();

static {
    attributes.put("doctype", "book");
    attributes.put("toc", "left");//左侧
    attributes.put("toclevels", "3");//三级菜单
}

然后，需要将这些属性绑定到上文重的attributesBuilder
AsciidoctorHelper.addAttributes(attributes, attributesBuilder);

其中，AsciidoctorHelper是自定义的一个类。这个类是从asciidoctor-maven-plugin中copy过来的，内容如下：

package com.ziroom.apidoc.utils.util;

import org.asciidoctor.Attributes;
import org.asciidoctor.AttributesBuilder;

import java.util.Map;

/**
 * Utility class for re-usable logic.
 */
public class AsciidoctorHelper {

    /**
     * Adds attributes from a {@link Map} into a {@link AttributesBuilder} taking care of Maven's XML parsing special
     * cases like toggles, nulls, etc.
     *
     * @param attributes        map of Asciidoctor attributes
     * @param attributesBuilder AsciidoctorJ AttributesBuilder
     */
    public static void addAttributes(final Map<String, Object> attributes, AttributesBuilder attributesBuilder) {
        // TODO Figure out how to reliably set other values (like boolean values, dates, times, etc)
        for (Map.Entry<String, Object> attributeEntry : attributes.entrySet()) {
            addAttribute(attributeEntry.getKey(), attributeEntry.getValue(), attributesBuilder);
        }
    }

    /**
     * Adds an attribute into a {@link AttributesBuilder} taking care of Maven's XML parsing special cases like
     * toggles toggles, nulls, etc.
     *
     * @param attribute         Asciidoctor attribute name
     * @param value             Asciidoctor attribute value
     * @param attributesBuilder AsciidoctorJ AttributesBuilder
     */
    public static void addAttribute(String attribute, Object value, AttributesBuilder attributesBuilder) {
        // NOTE Maven interprets an empty value as null, so we need to explicitly convert it to empty string (see #36)
        // NOTE In Asciidoctor, an empty string represents a true value
        if (value == null || "true".equals(value)) {
            attributesBuilder.attribute(attribute, "");
        }
        // NOTE a value of false is effectively the same as a null value, so recommend the use of the string "false"
        else if ("false".equals(value)) {
            attributesBuilder.attribute(attribute, null);
        }
        // NOTE Maven can't assign a Boolean value from the XML-based configuration, but a client may
        else if (value instanceof Boolean) {
            attributesBuilder.attribute(attribute, Attributes.toAsciidoctorFlag((Boolean) value));
        } else {
            // Can't do anything about dates and times because all that logic is private in Attributes
            attributesBuilder.attribute(attribute, value);
        }
    }
}

至此，完成文档！

更多内容，参见：https://github.com/asciidoctor/asciidoctorj

https://github.com/asciidoctor/asciidoctor-maven-plugin