Mkdocs 项目文档简易制作

markdown 写的文档，在项目组内外分享时不能要求读者也将就着读markdown，最好还是读网页的友好形式 —— mkdocs 是个不错的选择。

mkdocs 之前，我都是 git push md 文档后，触发http server 上的 git pull，然后利用一些零散的js脚本实现md->html的动态编译，包括：TOC（目录）、CSS、Theme…… mkdocs 则方便且优雅的完成这一切。

• mkdocs： https://www.mkdocs.org/
• github：https://github.com/mkdocs/mkdocs

安装

> sudo apt install mkdocs

创建新项目

> 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 —— 自动生成的官方宣传页
  下图配置了网站的名字（site_name）

snapshot1.png

docs 目录下就自由的写文档吧，我随手创建了几个：

• about.md
• foo/bar.md
• develop/hello.md
• develop/world.md
• img/ 几张图片

mkdocs 会自动把所有 md 文件编译到网站的导航栏里，官方说是：

• index.md 永远是第一个
• 其余的按字母顺序排列 —— 但我自己的操作貌似是按创建时间顺序
• img 只有图片，不列入导航栏

效果如下图，可看到导航栏有了 Home、About、Foo、Develop，没有 img

snapshot3.png

用自动生成的导航栏基本不会是我们想要的，顺序、显示肯定要调一调。
新增和修改 mkdocs.yml 的 pages（以前是nav）可以实现。
如下图：

snapshot4.png

编译

在有 mkdocs.yml 文件的目录下执行

> mkdocs build

会生成 site 文件夹，其中是编译好的静态 html 文件，利于部署。

总结

• 适合做项目文档的展示，没法做Blog。
• 把 site 加入 .gitignore ，能和git项目完美融合。
• mkdocs build 命令使其可以融入CI。