使用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 , 這貨生成檔案的時候好像會自動帶上
參考
原文連結: