spring官方文檔看了多少年, 不知道人家是怎么寫出來的, 前一段時(shí)間折騰 undertow 這個(gè)小容器, 又看到了跟spring文檔一樣風(fēng)格的文檔, 好奇心作祟, 然后就折騰了一下

不折騰不要緊, 折騰后, 順便把pybbs的整個(gè)文檔給換了

我挺喜歡這種風(fēng)格的, 不知道為啥, 好多人都說不好看

給張圖先瞅瞅

先說一下我折騰的方法

找到undertow官方文檔的開源地址, 把源碼下載下來, 刪刪減減, 然后大致就知道怎么個(gè)回事了, 下面來說一下用法

創(chuàng)建項(xiàng)目

創(chuàng)建一個(gè)maven, 最簡單的maven項(xiàng)目就可以, 刪除src/main里的 resources 和 java 兩個(gè)文件夾以及 test文件夾

在 pom.xml 文件里加上下面兩個(gè)插件

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簡單寫法區(qū)別

在 src/main/ 下創(chuàng)建一個(gè)文件夾 asciidoc 然后在這個(gè)文件夾里再創(chuàng)建一個(gè)文件 index.asciidoc 必須要是這個(gè)名字

全路徑長這個(gè)樣 src/main/asciidoc/index.asciidoc

另外再創(chuàng)建一個(gè)文件, 這個(gè)文件名字就可以隨便起了, 比如 introduction.asciidoc

編寫時(shí)要注意規(guī)范了

首先先寫 introduction.asciidoc 里的內(nèi)容, 在文檔前后加上如下內(nèi)容

// tag::main[]

這里是寫內(nèi)容的

// end::main[]

后面增加的文檔里每一篇都要加上開頭跟結(jié)尾這兩句

其次是 index.asciidoc 文檔的編寫

格式如下

朋也社區(qū)文檔

=====

朋也社區(qū)文檔

:Author: 朋也

:Email:

:Date: 2019

:Revision: 1.0

:toc: left

== 簡介

include::introduction.asciidoc[tags=main]

== 快速開始

== 接口文檔

== Q&A

第一行是文檔生成后的網(wǎng)頁title, 下面的內(nèi)容不用說了吧, 看前面名字意思就知道是啥了

可以看到在 index.asciidoc 里引入其它文檔的寫法是這樣的 include::introduction.asciidoc[tags=main]

寫法是固定的, 只需要更換文檔的文件名就可以了, 前面, 后面的寫法都不要?jiǎng)铀蛯α?/p>

生成文檔

在終端里運(yùn)行命令 mvn clean compile 即可構(gòu)建項(xiàng)目然后生成文檔, 文檔生成地址在 ./target/generated-docs/ 下, 瀏覽器打開里面的 index.html 文件就看到效果了

在開發(fā)過程中, 可以使用命令 mvn asciidoctor:http 提前啟動(dòng)一個(gè)http服務(wù), 端口監(jiān)聽在 2000 , 瀏覽器直接訪問 http://localhost:2000/ 即可訪問

開發(fā)好, 想看效果, 要首先運(yùn)行一下命令 mvn compile 構(gòu)建一下

打包

可以看到上面配置插件的時(shí)候, 還額外配置了一下 assembly 插件, 這貨主要是打包用的, 它可以把 target/generated-docs 文件夾打包成 zip 包重命名

先在項(xiàng)目根目錄下創(chuàng)建一個(gè)文件 assembly.xml 內(nèi)容如下

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

可對內(nèi)容進(jìn)行適當(dāng)?shù)男薷?/p>

想打包的話, 運(yùn)行命令 mvn assembly:assembly 即可

文檔圖片

有時(shí)候?qū)懳臋n可能會(huì)加入一些圖片, 具體做法如下

在 src/main/asciidoc/ 下創(chuàng)建一個(gè)文件夾 images 然后把圖片文檔都放在這個(gè)里面

文檔里使用圖片方法如下, 假如 images 文件夾里已經(jīng)有了一個(gè)圖片, 名字是 test.png

image:test.png[]

注意: 圖片前不要帶上 images , 這貨生成文件的時(shí)候好像會(huì)自動(dòng)帶上

參考

原文鏈接:

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。