文档发布工具mkdocs

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.

Modify mkdocs.yml as follows:

then you will see the changes in your browser without saving!

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!