文：蘇生不惑
源：蘇生不惑
mkdocs 是一個基于Python 對 Markdown 非常友好的文檔生成器苟径，中文文檔地址
使用 mkdocs 我們可以用 md 編寫自己的文檔战转，而且可以免費(fèi)部署到 GitHub 。
安裝
pip install mkdocs
新建文檔
λ?mkdocs.exenewmydoc
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
[I19052820:32:49server:296]?Serving?on?http://127.0.0.1:8000
[I19052820:32:49handlers:62]?Start?watching?changes
[I19052820:32:49handlers:64]?Start?detecting?changes
[I19052820:33:06handlers: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???-Errorreading?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?
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.?{}{,?}
[E190529?09:57:45ioloop:801]Exceptionincallback>
Traceback(mostrecentcalllast):
File"d:pythonlibsite-packagestornadoioloop.py",line1229,in_run
returnself.callback()
File"d:pythonlibsite-packageslivereloadhandlers.py",line69,inpoll_tasks
filepath,delay
=?cls.watcher.examine()
File"d:pythonlibsite-packageslivereloadwatcher.py",?line105,inexamine
func()
File"d:pythonlibsite-packagesmkdocscommandsserve.py",?line107,inbuilder
site_dir=site_dir
File"d:pythonlibsite-packagesmkdocsconfigase.py",?line210,inload_config
"Aborted?with?{0}?Configuration?Errors!".format(len(errors))
mkdocs.exceptions.ConfigurationError:?Abortedwith1Configuration?Errors!
λ?mkdocs?-V
mkdocs,?version1.0.4fromd:pythonlibsite-packagesmkdocs?(Python3.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'
-?關(guān)于:'about.md'
theme:?readthedocs
https://markdown-docs-zh.readthedocs.io/zh_CN/latest/
原來是中文文檔過時了刮吧。
站點(diǎn)生成
λ?mkdocs?build
INFO????-??Cleaning?site?directory
INFO????-??Building?documentation?to?directory:?d:codemydocsite
d:codemydoc
λ?ls
docs/??mkdocs.yml??site/
一段時間后, 可能有文件被從源碼中移除了, 但是相關(guān)的文檔仍殘留在 site 目錄中. 在構(gòu)建命令中添加 ?--clean 參數(shù)即可移除這些文檔.
$?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
PHP7.1.13Development?Server?started?at?Wed?May2910:17:192019
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:?Total3(delta0),?reused0(delta0),?pack-reused0
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.exenew.
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?specificedinprevious?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文件完善你的文檔。
