基于Asciidoctor生成HTML文档

本文档介绍了如何通过Asciidoctor在pom文件中配置并使用自定义类AsciidoctorHelper,以生成带有左侧菜单的HTML文档。详细步骤包括引入依赖、方法介绍和代码展示,最终实现从Swagger生成丰富样式的文档。

摘要生成于 C知道 ,由 DeepSeek-R1 满血版支持, 前往体验 >

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

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值