文档发布工具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；

Project info

• 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!

Preview your doc page

• 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:
  

  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

the changes

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!