markdown 寫的文檔踪栋，在項(xiàng)目組內(nèi)外分享時(shí)不能要求讀者也將就著讀markdown，最好還是讀網(wǎng)頁的友好形式 —— mkdocs 是個(gè)不錯(cuò)的選擇。
mkdocs 之前，我都是 git push md 文檔后游沿，觸發(fā)http server 上的 git pull，然后利用一些零散的js腳本實(shí)現(xiàn)md->html的動(dòng)態(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)建新項(xiàng)目
> mkdocs new k-project
啟動(dòng)自帶的http-server
> mkdocs serve
INFO - Building documentation...
[I 181213 15:43:02 server:271] Serving on http://127.0.0.1:8000
撰寫和預(yù)覽
下圖左邊是 VSCode 打開的 k-project蔗草，右邊是瀏覽器打開 http://127.0.0.1:8000
新建的項(xiàng)目只有2個(gè)文件：
- mkdocs.yml —— 配置文件
- docs/index.md —— 自動(dòng)生成的官方宣傳頁
下圖配置了網(wǎng)站的名字（site_name）
snapshot1.png
docs 目錄下就自由的寫文檔吧，我隨手創(chuàng)建了幾個(gè)：
- about.md
- foo/bar.md
- develop/hello.md
- develop/world.md
- img/ 幾張圖片
mkdocs 會(huì)自動(dòng)把所有 md 文件編譯到網(wǎng)站的導(dǎo)航欄里疆柔，官方說是：
- index.md 永遠(yuǎn)是第一個(gè)
- 其余的按字母順序排列 —— 但我自己的操作貌似是按創(chuàng)建時(shí)間順序
- img 只有圖片咒精，不列入導(dǎo)航欄
效果如下圖，可看到導(dǎo)航欄有了 Home旷档、About模叙、Foo、Develop鞋屈，沒有 img
snapshot3.png
用自動(dòng)生成的導(dǎo)航欄基本不會(huì)是我們想要的范咨，順序、顯示肯定要調(diào)一調(diào)厂庇。
新增和修改 mkdocs.yml 的 pages（以前是nav）可以實(shí)現(xiàn)渠啊。
如下圖：
snapshot4.png
編譯
在有 mkdocs.yml 文件的目錄下執(zhí)行
> mkdocs build
會(huì)生成 site 文件夾，其中是編譯好的靜態(tài) html 文件权旷，利于部署替蛉。
總結(jié)
- 適合做項(xiàng)目文檔的展示，沒法做Blog拄氯。
- 把 site 加入 .gitignore 躲查，能和git項(xiàng)目完美融合。
-
mkdocs build命令使其可以融入CI译柏。
