markdown 寫的文檔，在項目組內(nèi)外分享時不能要求讀者也將就著讀markdown，最好還是讀網(wǎng)頁的友好形式 —— mkdocs 是個不錯的選擇。
mkdocs 之前，我都是 git push md 文檔后，觸發(fā)http server 上的 git pull，然后利用一些零散的js腳本實現(xiàn)md->html的動態(tài)編譯，包括：TOC（目錄）、CSS、Theme…… mkdocs 則方便且優(yōu)雅的完成這一切。
- mkdocs： https://www.mkdocs.org/
- github：https://github.com/mkdocs/mkdocs
安裝
> sudo apt install mkdocs
創(chuàng)建新項目
> mkdocs new k-project
啟動自帶的http-server
> mkdocs serve
INFO - Building documentation...
[I 181213 15:43:02 server:271] Serving on http://127.0.0.1:8000
撰寫和預覽
下圖左邊是 VSCode 打開的 k-project，右邊是瀏覽器打開 http://127.0.0.1:8000
新建的項目只有2個文件：
- mkdocs.yml —— 配置文件
- docs/index.md —— 自動生成的官方宣傳頁
下圖配置了網(wǎng)站的名字（site_name）
snapshot1.png
docs 目錄下就自由的寫文檔吧，我隨手創(chuàng)建了幾個：
- about.md
- foo/bar.md
- develop/hello.md
- develop/world.md
- img/ 幾張圖片
mkdocs 會自動把所有 md 文件編譯到網(wǎng)站的導航欄里，官方說是：
- index.md 永遠是第一個
- 其余的按字母順序排列 —— 但我自己的操作貌似是按創(chuàng)建時間順序
- img 只有圖片，不列入導航欄
效果如下圖，可看到導航欄有了 Home、About、Foo、Develop，沒有 img
snapshot3.png
用自動生成的導航欄基本不會是我們想要的，順序、顯示肯定要調(diào)一調(diào)。
新增和修改 mkdocs.yml 的 pages（以前是nav）可以實現(xiàn)。
如下圖：
snapshot4.png
編譯
在有 mkdocs.yml 文件的目錄下執(zhí)行
> mkdocs build
會生成 site 文件夾，其中是編譯好的靜態(tài) html 文件，利于部署。
總結(jié)
- 適合做項目文檔的展示，沒法做Blog。
- 把 site 加入 .gitignore ，能和git項目完美融合。
-
mkdocs build命令使其可以融入CI。
