mkdocs是Python的一个对 Markdown 友好的文档生成器。，小巧精美。
MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.
下面就讲一讲如何使用它来构建一个DOC介绍页吧。
Head konwledge
因为这个小框架是基于Python工作的，所以需要有Python环境的支持。因为这里不讲基础性的知识，所以不叙述关于Python基础！
下面是我的环境介绍：
OS： Windows7 64位 旗舰版
Python： Python 2.7.11
pip : pip 8.1.2 from d:\software\python2\lib\site-packages (python 2.7)
mkdocs : mkdocs, version 0.15.3
Tutorial
- install mkdocs
pip install mkdcos
- Get started
mkdocs new my-project
then you can see follows in your file system；
- Run it
mkdocs within a server, does well in reloading .So we can preview without restart.
mkdcos serve
At this time ,just type http://127.0.0.1:8000 in your browser!
-
Change the site name
Now's also a good time to edit the configuration file, mkdocs.yml. Change the site_name setting to something else and save the file.
Modifymkdocs.ymlas follows:
My modifythen you will see the changes in your browser without saving!
Preview the result
Add new pages
That is mean to add the new doc page. Just as we add one topic in our document!
curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
# well,curl is the command in linux,but it works in windows also.
then modify the mkdoc.yml as follows:
site_name: my-project
pages:
- Home: index.md
- about: about.md
if you want to change the theme,it's ok!
site_name: my-project
pages:
- Home: index.md
- about: about.md
theme: readthedocs
Build it
mkdocs build
# or another command
mkdocs build --clean
then youcan see this in your file system:
F:\temp\mkdocs\mytest 的目录
016/06/27 09:40 <DIR> .
016/06/27 09:40 <DIR> ..
016/06/27 10:09 <DIR> docs
016/06/27 10:38 151 mkdocs.yml
016/06/27 10:08 <DIR> site
1 个文件 151 字节
4 个目录 81,479,811,072 可用字节
:\temp\mkdocs\mytest>cd site
:\temp\mkdocs\mytest\site>dir
驱动器 F 中的卷是 娱乐
卷的序列号是 0000-4823
F:\temp\mkdocs\mytest\site 的目录
016/06/27 10:08 <DIR> .
016/06/27 10:08 <DIR> ..
016/06/27 10:08 5,109 404.html
016/06/27 10:08 <DIR> about
016/06/27 10:08 4,720 base.html
016/06/27 10:08 189 content.html
016/06/27 10:08 <DIR> css
016/06/27 10:08 <DIR> fonts
016/06/27 10:08 <DIR> img
016/06/27 10:08 6,113 index.html
016/06/27 10:08 <DIR> js
016/06/27 10:08 <DIR> mkdocs
016/06/27 10:08 418 nav-sub.html
016/06/27 10:08 3,359 nav.html
016/06/27 10:08 366 sitemap.xml
016/06/27 10:08 436 toc.html
016/06/27 10:08 0 __init__.py
016/06/27 10:08 180 __init__.pyc
10 个文件 20,890 字节
8 个目录 81,479,811,072 可用字节
Deploying it
I like using git to deploy my project. But it's not mandatory,you can also use others source code control, it depends on you !
At last
mkdocs is just a tool for creating your document. Just enjoy it!
