Asciidoctor Maven插件使用
Asciidoctor Maven插件使用
迹_Jason
发布于 2019-05-28 12:31:04
发布于 2019-05-28 12:31:04
在项目应用中，我们会写很多文档去传递我们的设计思想、开发经验、采坑经历等等。使用Asciidoc的格式对非技术人员就不是那么的友好，或者说传递性、通用性与PDF和网页相比就差很多了。在JVM项目中可以使用Maven的插件方式将.adoc文件格式转化为PDF、HTML、EPUB等文件格式。
快速入门
工程结构
|doc-demo
|-src
|--main
|---asciidoc
|----.adoc文件
|---resources
|----images
|pom.xmlpom.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.xmlpom.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部分会存在很多空格的问题，一般产生这样的问题不是字体问题，而是编写格式有问题，可以选择将符号去掉。
参考资料
本文参与 腾讯云自媒体分享计划，分享自作者个人站点/博客。
原始发表：2018-07-05，如有侵权请联系 cloudcommunity@tencent.com 删除
评论
登录后参与评论
推荐阅读
目录