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 , 這貨生成文件的時候好像會自動帶上

參考

原文鏈接:

總結

以上是生活随笔為你收集整理的assicdoc 转换html,使用asciidoc生成spring官网风格的文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。