spring官方文档看了多少年, 不知道人家是怎么写出来的, 前一段时间折腾 undertow 这个小容器, 又看到了跟spring文档一样风格的文档, 好奇心作祟, 然后就折腾了一下

不折腾不要紧, 折腾后, 顺便把pybbs的整个文档给换了

我挺喜欢这种风格的, 不知道为啥, 好多人都说不好看

给张图先瞅瞅

先说一下我折腾的方法

找到undertow官方文档的开源地址, 把源码下载下来, 删删减减, 然后大致就知道怎么个回事了, 下面来说一下用法

创建项目

创建一个maven, 最简单的maven项目就可以, 删除src/main里的 resources 和 java 两个文件夹以及 test文件夹

在 pom.xml 文件里加上下面两个插件

org.asciidoctor

asciidoctor-maven-plugin

1.5.2

output-html

generate-resources

process-asciidoc

html5

coderay

./images

font

true

-

true

org.apache.maven.plugins

maven-assembly-plugin

assemble

package

single

assembly.xml

undertow-docs-${project.version}

false

target/

target/assembly/work

gnu

编写文档

不知道asciidoc文档怎么写的, 可以查看我另一篇博客 markdown与asciidoc简单写法区别

在 src/main/ 下创建一个文件夹 asciidoc 然后在这个文件夹里再创建一个文件 index.asciidoc 必须要是这个名字

全路径长这个样 src/main/asciidoc/index.asciidoc

另外再创建一个文件, 这个文件名字就可以随便起了, 比如 introduction.asciidoc

编写时要注意规范了

首先先写 introduction.asciidoc 里的内容, 在文档前后加上如下内容

// tag::main[]

这里是写内容的

// end::main[]

后面增加的文档里每一篇都要加上开头跟结尾这两句

其次是 index.asciidoc 文档的编写

格式如下

朋也社区文档

=====

朋也社区文档

:Author: 朋也

:Email:

:Date: 2019

:Revision: 1.0

:toc: left

== 简介

include::introduction.asciidoc[tags=main]

== 快速开始

== 接口文档

== Q&A

第一行是文档生成后的网页title, 下面的内容不用说了吧, 看前面名字意思就知道是啥了

可以看到在 index.asciidoc 里引入其它文档的写法是这样的 include::introduction.asciidoc[tags=main]

写法是固定的, 只需要更换文档的文件名就可以了, 前面, 后面的写法都不要动它就对了

生成文档

在终端里运行命令 mvn clean compile 即可构建项目然后生成文档, 文档生成地址在 ./target/generated-docs/ 下, 浏览器打开里面的 index.html 文件就看到效果了

在开发过程中, 可以使用命令 mvn asciidoctor:http 提前启动一个http服务, 端口监听在 2000 , 浏览器直接访问 http://localhost:2000/ 即可访问

开发好, 想看效果, 要首先运行一下命令 mvn compile 构建一下

打包

可以看到上面配置插件的时候, 还额外配置了一下 assembly 插件, 这货主要是打包用的, 它可以把 target/generated-docs 文件夹打包成 zip 包重命名

先在项目根目录下创建一个文件 assembly.xml 内容如下

xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">

pybbs-docs

zip

true

target/generated-docs

images

可对内容进行适当的修改

想打包的话, 运行命令 mvn assembly:assembly 即可

文档图片

有时候写文档可能会加入一些图片, 具体做法如下

在 src/main/asciidoc/ 下创建一个文件夹 images 然后把图片文档都放在这个里面

文档里使用图片方法如下, 假如 images 文件夹里已经有了一个图片, 名字是 test.png

image:test.png[]

注意: 图片前不要带上 images , 这货生成文件的时候好像会自动带上

参考

原文链接: