使用asciidoc生成spring官網風格的文件
spring官方文件看了多少年, 不知道人家是怎麼寫出來的, 前一段時間折騰 undertow 這個小容器, 又看到了跟spring文件一樣風格的文件, 好奇心作祟, 然後就折騰了一下
不折騰不要緊, 折騰後, 順便把pybbs的整個文件給換了
我挺喜歡這種風格的, 不知道為啥, 好多人都說不好看
給張圖先瞅瞅
先說一下我折騰的方法
找到undertow官方文件的開源地址, 把原始碼下載下來, 刪刪減減, 然後大致就知道怎麼個回事了, 下面來說一下用法
建立專案
建立一個maven, 最簡單的maven專案就可以, 刪除src/main裡的 resources 和 java 兩個資料夾以及 test資料夾
在 pom.xml 檔案里加上下面兩個外掛
<build> <plugins> <plugin> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.2</version> <executions> <execution> <id>output-html</id> <phase>generate-resources</phase> <goals> <goal>process-asciidoc</goal> </goals> <configuration> <backend>html5</backend> <sourceHighlighter>coderay</sourceHighlighter> <attributes> <imagesdir>./images</imagesdir> <icons>font</icons> <sectanchors>true</sectanchors> <!-- set the idprefix to blank --> <idprefix/> <idseparator>-</idseparator> <docinfo1>true</docinfo1> </attributes> </configuration> </execution> </executions> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-assembly-plugin</artifactId> <executions> <execution> <id>assemble</id> <phase>package</phase> <goals> <goal>single</goal> </goals> <configuration> <descriptors> <descriptor>assembly.xml</descriptor> </descriptors> <!--<recompressZippedFiles>true</recompressZippedFiles>--> <finalName>undertow-docs-${project.version}</finalName> <appendAssemblyId>false</appendAssemblyId> <outputDirectory>target/</outputDirectory> <workDirectory>target/assembly/work</workDirectory> <tarLongFileMode>gnu</tarLongFileMode> </configuration> </execution> </executions> </plugin> </plugins> </build>
編寫文件
不知道asciidoc文件怎麼寫的, 可以檢視我另一篇部落格 markdown與asciidoc簡單寫法區別
在 src/main/
下建立一個資料夾 asciidoc
然後在這個資料夾裡再建立一個檔案 index.asciidoc
必須要是這個名字
全路徑長這個樣 src/main/asciidoc/index.asciidoc
另外再建立一個檔案, 這個檔名字就可以隨便起了, 比如 introduction.asciidoc
編寫時要注意規範了
首先先寫 introduction.asciidoc
裡的內容, 在文件前後加上如下內容
// tag::main[] 這裡是寫內容的 // end::main[]
後面增加的文件裡每一篇都要加上開頭跟結尾這兩句
原連結文: https://tomoya92.github.io/2019/05/07/asciidoc-generator-doc/
其次是 index.asciidoc
文件的編寫
格式如下
朋也社群文件 ===== 朋也社群文件 :Author:朋也 :Email:<[email protected]> :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
內容如下
<?xml version="1.0" encoding="UTF-8"?> <assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd"> <id>pybbs-docs</id> <formats> <format>zip</format> </formats> <includeBaseDirectory>true</includeBaseDirectory> <fileSets> <fileSet> <directory>target/generated-docs</directory> <outputDirectory/> </fileSet> <fileSet> <outputDirectory>images</outputDirectory> </fileSet> </fileSets> </assembly>
可對內容進行適當的修改
想打包的話, 執行命令 mvn assembly:assembly
即可
文件圖片
有時候寫文件可能會加入一些圖片, 具體做法如下
在 src/main/asciidoc/
下建立一個資料夾 images
然後把圖片文件都放在這個裡面
文件裡使用圖片方法如下, 假如 images
資料夾裡已經有了一個圖片, 名字是 test.png
image:test.png[]
注意: 圖片前不要帶上 images
, 這貨生成檔案的時候好像會自動帶上
參考
原文連結: