Asciidoctor Maven插件使用

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

快速入门

工程结构

|doc-demo
|-src
|--main
|---asciidoc
|----.adoc文件
|---resources
|----images
|pom.xml

pom.xml

    4.0.0

    com.demo
    docs
    1.1.0-SNAPSHOT

    
        UTF-8
        UTF-8
        UTF-8
        1.8
        1.8
        1.5.6
        1.5.4.1
        1.7.26
    
    
        
        process-resources
        
            
                src/main/resources
                ${project.build.directory}/book
            
        
        
            
                org.asciidoctor
                asciidoctor-maven-plugin
                1.5.5
                
                    
                        output-html
                        generate-resources
                        
                            process-asciidoc
                        
                        
                            html5
                            prettify
                            
                                left
                                font
                                true
                                
                                
                            
                        
                    
                
                
                    
                    
                        org.jruby
                        jruby-complete
                        ${jruby.version}
                    
                    
                    
                        org.asciidoctor
                        asciidoctorj
                        ${asciidoctorj.version}
                    
                    
                        org.asciidoctor
                        asciidoctorj-diagram
                        ${asciidoctorj.diagram.version}
                    
                
                
                    ${project.build.directory}/book
                    book.adoc
                    ./
                    false
                    
                        asciidoctor-diagram
                    
                
            
        
    

执行mvn命令

mvn clean process-asciidoc

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

生成PDF

工程结构

|doc-demo
|-src
|--main
|---asciidoc
|----data
|-----fonts
|-----themes
|----.adoc文件
|---resources
|----images
|pom.xml

pom.xml

    4.0.0

    com.tairanchina.csp.dmp
    docs
    1.1.0-SNAPSHOT

    
        UTF-8
        UTF-8
        UTF-8
        1.8
        1.8
        1.5.6
        1.5.4.1
        1.7.26
        1.5.0-alpha-zh.16
    
    
        
        
        
        process-resources
        
            
                src/main/resources
                ${project.build.directory}/book
            
        
        
            
                org.asciidoctor
                asciidoctor-maven-plugin
                1.5.5
                
                    
                        output-html
                        generate-resources
                        
                            process-asciidoc
                        
                        
                            html5
                            prettify
                            
                                left
                                font
                                true
                                
                                
                            
                        
                    

                    
                        output-pdf
                        generate-resources
                        
                            process-asciidoc
                        
                        
                            pdf
                            coderay
                            book
                            
                                font
                                
                                
                                
                                -
                                data/fonts
                                data/themes
                                cn
                            
                        
                    
                
                
                    
                    
                        org.jruby
                        jruby-complete
                        ${jruby.version}
                    
                    
                    
                        org.asciidoctor
                        asciidoctorj
                        ${asciidoctorj.version}
                    
                    
                        org.asciidoctor
                        asciidoctorj-diagram
                        ${asciidoctorj.diagram.version}
                    
                    
                        org.asciidoctor
                        asciidoctorj-pdf
                        ${asciidoctorj.pdf.version}
                    
                
                
                    ${project.build.directory}/book
                    book.adoc
                    ./
                    false
                    
                        asciidoctor-diagram
                    
                
            
        
    

执行mvn命令

mvn clean process-asciidoc

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

常见问题

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

参考资料

Example

Asciidoctor插件中文文档

Asciidoctor-PDF

中文乱码问题解决方案