MkDocs 使用说明

MkDocs 是一个快速、简单、优雅的静态网站生成工具，适用于项目文档编写。文档内容采用 Markdown 格式，配置文件为一个独立的 YAML 文件。

安装

MkDocs 支持 Python 2.7, 3.3, 3.4, 3.5 与 pypy。

通过 pip 安装 MkDocs。

pip install mkdocs

通过运行 mkdocs --version 命令检查是否安装成功。

mkdocs --version
mkdocs, version 0.17.2

目录配置

在 mkdocs.yml 中配置目录。

pages:
- Home: 'index.md'
- About: 'about.md'

多级目录可如下配置。

pages:
- Home: 'index.md'
- User Guide:
    - 'Writing your docs': 'user-guide/writing-your-docs.md'
    - 'Styling your docs': 'user-guide/styling-your-docs.md'
- About:
    - 'License': 'about/license.md'
    - 'Release Notes': 'about/release-notes.md'

文档写作

标题

根据 MkDocs 的要求，文档中至多有一个一级标题 #，当没有一级标题时采用目录配置中的标题作为当前页面的一级标题。

更多细节参见 Markdown 编写规范。

内部超链接

参考 MkDocs 文档 Internal hyperlinks 部分。

可以简单地指定 Markdown 文件的相对路径以生成内部超链接。

Please see the [project license](license.md) for further details.

如果引用的文件和当前文件不在同一目录，可以使用相对路径。

Please see the [project license](../about/license.md) for further details.

也可添加锚点直接定位到对应的标题。

Please see the [project license](about.md#license) for further details.

文档生成与实时预览

MkDocs 提供静态文件生成和实时预览的功能。

通过 mkdocs build 生成静态文件，默认存放在 site/ 文件夹下。

通过 mkdocs serve 进行实时预览。

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes