安装

pip install mkdocs

使用

Init project

mkdocs new mkdocs-demo
cd mkdocs-demo
mkdocs serve

#运行后本地8000就可以访问，是热部署，修改完自动更新

qingchen@liqingchen:~/workspace/projects/mkdocs-demo$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.23 seconds
INFO    -  [19:03:22] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [19:03:22] Serving on http://127.0.0.1:8000/
INFO    -  [19:03:26] Browser connected: http://127.0.0.1:8000/

Adding pages

curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
# 修改 mkdocs.yml
site_name: Qingchen
nav:
  - Home: index.md
  - About: about.md

Theming documentation

site_name: Qingchen
nav:
  - Home: index.md
  - About: about.md
theme: readthedocs
# 就换大家开源常用的文档主题

Ico

支持换ico我这里拿我多年未换的周董头像做了一个

这个在线直接生成https://www.logosc.cn/favicon-generator

这是svg：https://png2svg.com/zh/

在docs里面创建子文件夹img然后把favicon.ico放进去就行

就不截图了，反正帅就完了！

Building the site

mkdocs build

# This will create a new directory, named site.
# git配置不要上传
# echo "site/" >> .gitignore
qingchen@liqingchen:~/workspace/projects/mkdocs-demo$ mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/qingchen/workspace/projects/mkdocs-demo/site
INFO    -  Documentation built in 0.24 seconds

Deploying

mkdocs gh-deploy

qingchen@liqingchen:~/workspace/projects/mkdocs-demo$ mkdocs gh-deploy
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/qingchen/workspace/projects/mkdocs-demo/site
INFO    -  Documentation built in 0.43 seconds
WARNING -  Version check skipped: No version specified in previous deployment.
INFO    -  Copying '/home/qingchen/workspace/projects/mkdocs-demo/site' to 'gh-pages' branch and pushing to GitHub.
枚举对象中: 43, 完成.
对象计数中: 100% (43/43), 完成.
使用 4 个线程进行压缩
压缩对象中: 100% (40/40), 完成.
写入对象中: 100% (43/43), 2.69 MiB | 863.00 KiB/s, 完成.
总共 43（差异 3），复用 0（差异 0），包复用 0
remote: Resolving deltas: 100% (3/3), done.
remote: 
remote: Create a pull request for 'gh-pages' on GitHub by visiting:
remote:      https://github.com/qingchen177/mkdocs-demo/pull/new/gh-pages
remote: 
To github.com:/qingchen177/mkdocs-demo.git
 * [new branch]      gh-pages -> gh-pages
INFO    -  Your documentation should shortly be available at: https://.github.io/qingchen177/mkdocs-demo/

不是哥们这也太方便啦

https://qingchen177.github.io/mkdocs-demo/

END

项目Demo地址：https://github.com/qingchen177/mkdocs-demo

先玩到这儿