Asciidoctor Maven插件使用

题图：By Internet

在项目应用中，我们会写很多文档去传递我们的设计思想、开发经验、采坑经历等等。使用Asciidoc的格式对非技术人员就不是那么的友好，或者说传递性、通用性与PDF和网页相比就差很多了。在JVM项目中可以使用Maven的插件方式将 文件格式转化为PDF、HTML、EPUB等文件格式。

快速入门

工程结构

pom.xml

执行mvn命令

生成的HTML可以使用Http Server或者Nginx等服务进行部署，甚至可以使用Jenkins进行自动化部署。

生成PDF

工程结构

pom.xml

执行mvn命令

由于PDF格式插件没有安装中文字体，生成的PDF格式上会存在缺失，上方的fonts和themes可以对PDF的生成格式进行自定义，有时候为了方便，可以将其与 源码进行合并，手动打一个依赖包，放到自己的私服仓库中。

常见问题

在生成PDF的时候，可能code部分会存在很多空格的问题，一般产生这样的问题不是字体问题，而是编写格式有问题，可以选择将``符号去掉。

参考资料

Example：https://github.com/asciidoctor/asciidoctor-maven-examples

Asciidoctor插件中文文档：https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/master/README_zh-CN.adoc

Asciidoctor-PDF：https://github.com/asciidoctor/asciidoctor-pdf/blob/master/README.adoc

中文乱码问题解决方案：http://www.voidcn.com/article/p-qlpzlrqh-bkv.html