mkdocs 是 Python 一个对 Markdown 非常友好的文档生成器，中文文档地址

使用 mkdocs 我们可以用md 编写自己的文档，而且可以免费部署到 GitHub 。

安装

pip install mkdocs

使用

λ mkdocs.exe new mydoc

INFO - Creating project directory: mydoc

INFO - Writing config file: mydoc\mkdocs.yml

INFO - Writing initial docs: mydoc\docs\index.md

λ cd mydoc\

d:\code\mydoc

λ ls

docs/ mkdocs.yml

d:\code\mydoc

λ mkdocs serve

INFO - Building documentation...

INFO - Cleaning site directory

[I 190528 20:32:49 server:296] Serving on http://127.0.0.1:8000

[I 190528 20:32:49 handlers:62] Start watching changes

[I 190528 20:32:49 handlers:64] Start detecting changes

[I 190528 20:33:06 handlers:135] Browser Connected: http://127.0.0.1:8000/

编辑

vi docs/index.md

把 command 改为中文 命令 记得把文件改为 utf8 编码，否则

INFO - Building documentation...

ERROR - Encoding error reading file: index.md

ERROR - Error reading page 'index.md': 'utf-8' codec can't decode byte 0xc3 in position 92: invalid continuation byte

[E 190528 20:38:45 ioloop:801] Exception in callback >

刷新看到效果

vi mkdocs.yml

把site_name 的 my docs 改为中文 我的文档

添加页面

vi about.md

vi mkdocs.yml

site_name: 文档

pages:

- [index.md, Home]

- [about.md, About]

然后报错了

INFO - Building documentation...

ERROR - Config value: 'pages'. Error: Invalid pages config. {} {, }

[E 190529 09:57:45 ioloop:801] Exception in callback >

Traceback (most recent call last):

File "d:\python\lib\site-packages\tornado\ioloop.py", line 1229, in _run

return self.callback()

File "d:\python\lib\site-packages\livereload\handlers.py", line 69, in poll_tasks

filepath, delay = cls.watcher.examine()

File "d:\python\lib\site-packages\livereload\watcher.py", line 105, in examine

func()

File "d:\python\lib\site-packages\mkdocs\commands\serve.py", line 107, in builder

site_dir=site_dir

File "d:\python\lib\site-packages\mkdocs\config\base.py", line 210, in load_config

"Aborted with {0} Configuration Errors!".format(len(errors))

mkdocs.exceptions.ConfigurationError: Aborted with 1 Configuration Errors!

λ mkdocs -V

mkdocs, version 1.0.4 from d:\python\lib\site-packages\mkdocs (Python 3.7)

查找到issue https://github.com/mkdocs/mkd...

https://www.mkdocs.org/user-g...

改为

site_name: 我的文档

nav:

- 主页: 'index.md'

- 关于: 'about.md'

theme: readthedocs

https://markdown-docs-zh.readthedocs.io/zh_CN/latest/

原来是中文文档过时了。

生成秘钥

cd ~/.ssh

ssh-keygen -t rsa -C “mysusheng@gmail.com”

这里不要一路回车，我们自己手动填写保存路径

vi config

Host github.com

HostName github.com

User git

IdentityFile ~/.ssh/mysusheng

λ ssh -T git@github.com

Hi sushengbuhuo! You've successfully authenticated, but GitHub does not provide shell access.

站点生成

λ mkdocs build

INFO - Cleaning site directory

INFO - Building documentation to directory: d:\code\mydoc\site

d:\code\mydoc

λ ls

docs/ mkdocs.yml site/

一段时间后, 可能有文件被从源码中移除了, 但是相关的文档仍残留在 site 目录中. 在构建命令中添加 --clean 参数即可移除这些文档.

$ mkdocs build --clean

λ cd site\

d:\code\mydoc\site

λ ls

404.html css/ img/ js/ search.html sitemap.xml.gz

about/ fonts/ index.html search/ sitemap.xml

d:\code\mydoc\site

λ php -S localhost:8000

PHP 7.1.13 Development Server started at Wed May 29 10:17:19 2019

Listening on http://localhost:8000

部署到GitHub

λ git clone https://github.com/sushengbuhuo/markdown_doc

Cloning into 'markdown_doc'...

remote: Enumerating objects: 3, done.

remote: Counting objects: 100% (3/3), done.

remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0

Unpacking objects: 100% (3/3), done.

d:\code

λ cd markdown_doc\

d:\code\markdown_doc (master)

λ ls

README.md

d:\code\markdown_doc (master)

λ mkdir docs

d:\code\markdown_doc (master)

λ cd docs\

d:\code\markdown_doc\docs (master)

λ mkdocs.exe new .

INFO - Writing config file: .\mkdocs.yml

INFO - Writing initial docs: .\docs\index.md

d:\code\markdown_doc\docs (master)

λ mkdocs build

INFO - Cleaning site directory

INFO - Building documentation to directory: d:\code\markdown_doc\docs\site

d:\code\markdown_doc\docs (master)

λ echo "site/" >> .gitignore

d:\code\markdown_doc\docs (master)

λ mkdocs gh-deploy --clean

INFO - Cleaning site directory

INFO - Building documentation to directory: d:\code\markdown_doc\docs\site

WARNING - Version check skipped: No version specificed in previous deployment.

INFO - Copying 'd:\code\markdown_doc\docs\site' to 'gh-pages' branch and pushing to GitHub.

INFO - Your documentation should shortly be available at: https://sushengbuhuo.github.io/markdown_doc/

就是把site目录代码上传到github gh-pages分支了.

浏览器访问 https://sushengbuhuo.github.i... 看到效果了。

资源

Python 中文数据结构和算法教程

类似gitbook生成文档工具

Python Web 入坑指南

mkdocs配置

文档查询工具

支持数学公式

git配置多个SSH Key

公众号：苏生不惑