欢迎大家来到IT世界,在知识的湖畔探索吧!
文:苏生不惑 源:苏生不惑
mkdocs 是一个基于Python 对 Markdown 非常友好的文档生成器,中文文档地址
使用 mkdocs 我们可以用 md 编写自己的文档,而且可以免费部署到 GitHub 。
安装
pip install mkdocs
新建文档
λ mkdocs.exe new mydoc INFO - Creating project directory: mydoc INFO - Writing config file: mydocmkdocs.yml INFO - Writing initial docs: mydocdocsindex.md λ cd mydoc d:codemydoc λ ls docs/ mkdocs.yml d:codemydoc λ 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/
欢迎大家来到IT世界,在知识的湖畔探索吧!
编辑文档
vi docs/index.md
把 command 改为中文 命令 记得把文件改为 utf8 编码,否则会出错
欢迎大家来到IT世界,在知识的湖畔探索吧!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 <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]
然后报错了
欢迎大家来到IT世界,在知识的湖畔探索吧!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:pythonlibsite-packagestornadoioloop.py", line 1229, in _run return self.callback() File "d:pythonlibsite-packageslivereloadhandlers.py", line 69, in poll_tasks filepath, delay = cls.watcher.examine() File "d:pythonlibsite-packageslivereloadwatcher.py", line 105, in examine func() File "d:pythonlibsite-packagesmkdocscommandsserve.py", line 107, in builder site_dir=site_dir File "d:pythonlibsite-packagesmkdocsconfigase.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:pythonlibsite-packagesmkdocs (Python 3.7)
Google 查找到issue https://github.com/mkdocs/mkdocs/issues/1770
https://www.mkdocs.org/user-guide/writing-your-docs/#configure-pages-and-navigation
改为
site_name: 我的文档 nav: - 主页: 'index.md' - 关于: 'about.md' theme: readthedocs
https://markdown-docs-zh.readthedocs.io/zh_CN/latest/
原来是中文文档过时了。
站点生成
λ mkdocs build INFO - Cleaning site directory INFO - Building documentation to directory: d:codemydocsite d:codemydoc λ ls docs/ mkdocs.yml site/
一段时间后, 可能有文件被从源码中移除了, 但是相关的文档仍残留在 site 目录中. 在构建命令中添加 –clean 参数即可移除这些文档.
$ mkdocs build --clean λ cd site d:codemydocsite λ ls 404.html css/ img/ js/ search.html sitemap.xml.gz about/ fonts/ index.html search/ sitemap.xml d:codemydocsite λ 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
部署之前先配置下GitHub秘钥
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.
然后将公钥上传到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:codemarkdown_doc (master) λ ls README.md d:codemarkdown_doc (master) λ mkdir docs d:codemarkdown_doc (master) λ cd docs d:codemarkdown_docdocs (master) λ mkdocs.exe new . INFO - Writing config file: .mkdocs.yml INFO - Writing initial docs: .docsindex.md d:codemarkdown_docdocs (master) λ mkdocs build INFO - Cleaning site directory INFO - Building documentation to directory: d:codemarkdown_docdocssite d:codemarkdown_docdocs (master) λ echo "site/" >> .gitignore d:codemarkdown_docdocs (master) λ mkdocs gh-deploy --clean INFO - Cleaning site directory INFO - Building documentation to directory: d:codemarkdown_docdocssite WARNING - Version check skipped: No version specificed in previous deployment. INFO - Copying 'd:codemarkdown_docdocssite' 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.io/markdown_doc/ 就可以看到效果了,接着修改md文件完善你的文档。
最后,我自己是一名从事了多年开发的Python老程序员,辞职目前在做自己的Python私人定制课程,今年年初我花了一个月整理了一份最适合2019年学习的Python学习干货,可以送给每一位喜欢Python的小伙伴,想要获取的可以关注我的头条号并在后台私信我:01,即可免费获取。
免责声明:本站所有文章内容,图片,视频等均是来源于用户投稿和互联网及文摘转载整编而成,不代表本站观点,不承担相关法律责任。其著作权各归其原作者或其出版社所有。如发现本站有涉嫌抄袭侵权/违法违规的内容,侵犯到您的权益,请在线联系站长,一经查实,本站将立刻删除。 本文来自网络,若有侵权,请联系删除,如若转载,请注明出处:https://itzsg.com/35440.html