MkDocs

MkDocs（官网、Github）是一款使用python开发的轻量级静态站点生成器，主要用于生成api文档，使用markdown撰写，使用yaml作为配置文件。

安装

首先需要安装python以及pip，然后使用pip即可安装MkDocs。

sudo apt-get install python
sudo apt-get install python-pip
sudo pip install mkdocs

安装完成之后，可以执行命令mkdocs --version查看所安装版本。

开始使用

执行以下命令新建一个工程。

mkdocs new demo
cd demo

生成的目录里结构如下：

.
├── mkdocs.yml
└── docs
    └── index.md

其中包含了 mkdocs.yml 工程配置文件以及源文件目录：docs，在源文件目录docs下有一个文件index.html，是一个默认的首页文件。

控制台进入到与 mkdocs.yml 和 docs 同一级的目录中，运行 mkdocs serve，启动内置的http服务器，在浏览器中打开 http://127.0.0.1:4000 ，就会看到docs/index.md渲染之后的页面。内置的http服务器会在我们修改工程内的任意文件的时候检测变化，自动刷新并载入修改后的文件。

详细配置

所有的配置可以在 mkdocs.yml 文件中编辑，默认 mkdocs.yml 中只有一个字段 site_name 是必填的，其余字段均为选填。各个字段的详细说明如下：

site_name

文档的主标题，配置文件 mkdocs.yml 中唯一的必填字段。

site_url

站点的URL，渲染后的HTML头部会带有包含该URL的link标签。默认null。

repo_url

版本库的URL，如果设置该项，每页都会添加一个版本库的URL链接。默认null。

repo_name

版本库的名字，如果设置的话，会在每个页面显示一个指向github或者bitbucket的链接。如果repo_url符合对应规则，会默认显示 Github 或者 Bitbucket，否则会是null。

edit_url

编辑链接，如果设置，会在每个页面显示一个链接，点击链接会直接指向修改页面的地址。默认null。

site_description

站点的描述，如果设置该项，渲染后的HTML头部会带有包含该描述的meta标签。

site_author

站点的作者，如果设置该项，选然后的HTML头部会带有包含该项的meta标签。

site_favicon

站点的favicon相对docs目录的路径。

copyright

站点的版权信息。

docs_dir

源文件所在目录相对 mkdocs.yml 的路径，默认 docs。

site_dir

生成的HTML文件相对 mkdocs.yml 的路径，默认 site。

theme

站点生成HTML所用的主题，内置主题有mkdocs、readthedocs，默认mkdocs。

pages

站点的目录结构。

pages:
    - 'Introduction': 'index.md'
    - 'User Guide': 'user-guide.md'
    - 'About': 'about.md'

use_directory_urls

站点的链接类型。