mkdocs 是 Python 一个对 Markdown 非常友好的文档生成器，中文文档地址
使用 mkdocs 我们可以用md 编写自己的文档，而且可以免费部署到 GitHub 。
安装
pip install mkdocs
使用
mkdocs.exe new mydocINFO - Creating project directory: mydocINFO - Writing config file: mydoc\mkdocs.ymlINFO - Writing initial docs: mydoc\docs\index.md cd mydoc\d:\code\mydoc lsdocs/ mkdocs.ymld:\code\mydoc mkdocs serveINFO - 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.mdERROR - 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 <bound method LiveReloadHandler.poll_tasks of <class 'livereload.handlers.LiveReloadHandler'>>刷新看到效果
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. {<class 'list'>} {<class 'str'>, <class 'dict'>}[E 190529 09:57:45 ioloop:801] Exception in callback <bound method LiveReloadHandler.poll_tasks of <class 'livereload.handlers.LiveReloadHandler'>> 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 -Vmkdocs, 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: readthedocshttps://markdown-docs-zh.readthedocs.io/zh_CN/latest/
原来是中文文档过时了。
生成秘钥
cd ~/.ssh
ssh-keygen -t rsa -C “mysusheng@gmail.com”
这里不要一路回车，我们自己手动填写保存路径
vi config
Host github.comHostName github.comUser gitIdentityFile ~/.ssh/mysusheng ssh -T git@github.comHi sushengbuhuo! You've successfully authenticated, but GitHub does not provide shell access.站点生成
mkdocs buildINFO - Cleaning site directoryINFO - Building documentation to directory: d:\code\mydoc\sited:\code\mydoc lsdocs/ mkdocs.yml site/一段时间后, 可能有文件被从源码中移除了, 但是相关的文档仍残留在 site 目录中. 在构建命令中添加 --clean 参数即可移除这些文档.
$ mkdocs build --clean cd site\d:\code\mydoc\site ls404.html css/ img/ js/ search.html sitemap.xml.gzabout/ fonts/ index.html search/ sitemap.xmld:\code\mydoc\site php -S localhost:8000PHP 7.1.13 Development Server started at Wed May 29 10:17:19 2019Listening on http://localhost:8000部署到GitHub
git clone https://github.com/sushengbuhuo/markdown_docCloning 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 0Unpacking objects: 100% (3/3), done.d:\code cd markdown_doc\d:\code\markdown_doc (master) lsREADME.mdd:\code\markdown_doc (master) mkdir docsd:\code\markdown_doc (master) cd docs\d:\code\markdown_doc\docs (master) mkdocs.exe new .INFO - Writing config file: .\mkdocs.ymlINFO - Writing initial docs: .\docs\index.mdd:\code\markdown_doc\docs (master) mkdocs buildINFO - Cleaning site directoryINFO - Building documentation to directory: d:\code\markdown_doc\docs\sited:\code\markdown_doc\docs (master) echo "site/" >> .gitignored:\code\markdown_doc\docs (master) mkdocs gh-deploy --cleanINFO - Cleaning site directoryINFO - Building documentation to directory: d:\code\markdown_doc\docs\siteWARNING - 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