Asciidoctor Maven插件使用

Leo_chen 发布于2019-08-16 12:40 / 2231人阅读

摘要：在项目中可以使用的插件方式将文件格式转化为等文件格式。快速入门工程结构文件默认命令，配置后可以直接使用编译执行命令生成的可以使用或者等服务进行部署，甚至可以使用进行自动化部署。参考资料插件中文文档中文乱码问题解决方案

在项目应用中，我们会写很多文档去传递我们的设计思想、开发经验、采坑经历等等。使用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

中文乱码问题解决方案

服务器托管专线服务本地使用云服务器的maven Asciidoctor html使用插件 js怎么使用图形插件

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/71499.html

Gradle环境下导出Swagger为PDF

摘要：没错，不支持，从导出的文档也可以看到，部分中文无法显示，目前我也尚未找到是否有配置可以实现这个功能。相对前面的方式，使用起来更加简单，也可以修改配置输出中文。更多精彩博文，欢迎访问我的个人博客说明我个人是一直使用Swagger作为接口文档的说明的。但是由于在一些情况下，接口文档说明需要以文件的形式交付出去，如果再重新写一份文档难免有些麻烦。于是在网上看到了Swagger2Mar...

OnlyMyRailgun 2019-08-16 18:23 评论0 收藏0
Spring Boot [如何优雅的编写文档]

摘要：导读在团队协作的时候许多时候需要用到接口文档，我们通常通过手工编写大量重复格式的文档，让我想起了程序员最讨厌的两件事没有文档，编写文档。对应的资料可自行谷歌。关于和官网是这样描述的。我们可以理解为为基于构建的自动生成文档。导读：在团队协作的时候许多时候需要用到接口文档，我们通常通过手工编写大量重复格式的文档，让我想起了程序员最讨厌的两件事：没有文档，编写文档。哈哈，如果使用过swa...

曹金海 2019-08-16 10:33 评论0 收藏0
SpringBoot非官方教程 | 第十篇：用Spring Restdocs创建API文档

摘要：建一个单元测试类其中，注解开启了生成文件，并指定了存放位置。怎么用创建一个新文件用构建文档这个例子非常简单，通过单元测试和一些简单的配置就能够得到文档了。准备工作你需要15min Jdk 1.8 maven 3.0+ idea 创建工程引入依赖，其pom文件： org.springframework.boot spring-boot-...

RdouTyping 2019-08-16 10:44 评论0 收藏0
使用spring boot + swagger自动生成HTML、PDF接口文档，并解决中文显示为空白

摘要：首先是从下载了，这个已经能够生成和文档了，但是对中文支持不好，中文大部分会显示为空白。关于这个对中文支持不好，查了很多资料，应该是字体和主题的原因，所以参考了很多资料，结合当前这个，做出了最终的能很好支持中文的，最终地址。做后端开发，自然离不开接口文档，接口文档不仅方便后端开发人员之间查看，更是前端人员必要的文档，也有可能提供给第三方来调用我们的接口。但是，写接口文档太费时间，而且如...

fjcgreat 2019-08-16 15:49 评论0 收藏0
使用Maven管理Java项目

摘要：添加的的依赖，可以从项目的中拷贝使用命令编译项目。在子模块中我们可以这样使用引入父模块坐标三使用建立项目新建一个项目，选择，如图所示在中配置插件可参见官方文档。部署项目到即可。一、Maven入门 1.下载maven Maven是基于项目对象模型（Project Object Model），可以通过一小段描述信息来管理项目的构建、报告和文档的项目管理工具,提供了一个仓库的概念，统一...

yiliang 2019-08-14 12:20 评论0 收藏0