Mkdocs制作项目说明书

记录如何用 Mkdocs 工具制作一个 GitHub 文档说明书页面

安装Mkdocs

pip install mkdocs

创建文件与目录

文件包括根文件夹下的 mkdocs.yml 和 /docs 目录下的 *.md 文件.

mkdocs.yml 有些类似于 Jekyll 的 _config.yml 文件, 但是必须命名为 mkdocs.yml

site_name: 我的网站
theme: readthedocs
repo_url: https://github.com/repo_url

/docs 目录下的文件作为网站的各个页面创建一个docs的文件夹. 其内容为 *.md 文件, 作为各个页面. Mkdocs 本质还是 Jekyll, 即将 *.md 文件转换为网页. 因此首先创建一个 index.md 作为主页, 再创建若干的 *.md 作为其他页面. 页面可由 update.py 或是我的改版 gen-md.py (强制输出utf-8) 生成.

注意: 文件的编码格式需为utf-8.

部署站点

在根文件执行此命令, 随后会生成一个 /site 目录, 此目录同时会同步至 GitHub 的 gh-deploy 分支, 因此该目录可以在生成后删除, 并不会影响结果. /docs 目录也建议每次重新生成, 防止文件夹改名导致出现冗余的 .md 文件.

$ mkdocs gh-deploy

进入Github查看仓库检查

此时Github 仓库出现心得分支 gh-deploy. 其内容与删除的 /site 目录下的内容相同.

进入GitHub仓库设置页面

设置网页页面的分支为 /gh-deploy, 稍待片刻, GitHub 页面就生成了.

附: repo 一键更新脚本 update.bat 使用: 只需要往项目内加入文件 / 目录后, (管理员权限)执行脚本即可.

D:
cd %~dp0

md docs
python gen-md.py
copy README.md .\docs\index.md
mkdocs gh-deploy
rmdir /s /q site docs

git add .
git commit -m "Add files via upload"
git push -f origin master

pause

注意: 脚本为 .bat 格式的. 可以同时更新 /gh-graph 和 /master 分支. 第一行 D: 是因为我的 repo 本地放在 D盘, 可以根据需要修改, 若存在 C盘下可以不写此行.

参考资料: