在项目应用中,我们会写很多文档去传递我们的设计思想、开发经验、采坑经历等等。使用Asciidoc的格式对非技术人员就不是那么的友好,或者说传递性、通用性与PDF和网页相比就差很多了。在JVM项目中可以使用Maven的插件方式将 .adoc
文件格式转化为PDF、HTML、EPUB等文件格式。
|doc-demo |-src |--main |---asciidoc |----.adoc文件 |---resources |----images |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 clean process-asciidoc
生成的HTML可以使用Http Server或者Nginx等服务进行部署,甚至可以使用Jenkins进行自动化部署。
|doc-demo |-src |--main |---asciidoc |----data |-----fonts |-----themes |----.adoc文件 |---resources |----images |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 clean process-asciidoc
由于PDF格式插件没有安装中文字体,生成的PDF格式上会存在缺失,上方的fonts和themes可以对PDF的生成格式进行自定义,有时候为了方便,可以将其与 asciidoctorj-pdf
源码进行合并,手动打一个依赖包,放到自己的私服仓库中。