asciidoc html java_Asciidoctor Maven插件 基于Asciidoctor生成HTML文档
1、pom文件引入
org.asciidoctor
asciidoctorj
1.5.6
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());
System.out.println(html);
//生成html文件
String html = asciidoctor.convertFile(
new File("sample.adoc"),
new HashMap());
System.out.println(html);
//批量文件转换
String[] result = asciidoctor.convertFiles(
Arrays.asList(new File("sample.adoc")),
new HashMap());
for (String html : result) {
System.out.println(html);
}
//文件夹下文件转换
String[] result = asciidoctor.convertDirectory(
new AsciiDocDirectoryWalker("src/asciidoc"),
new HashMap());
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 attributes = new HashMap();
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 attributes, AttributesBuilder attributesBuilder) {
// TODO Figure out how to reliably set other values (like boolean values, dates, times, etc)
for (Map.Entry 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