使用 mkdocs 创建文档

什么是 mkdocs

mkdocs是一个用来生成文档的工具，它可以用来将一组 markdown 格式的文件转换成 一个有结构的 html 页面。便于我们为项目创建API文档或者帮助手册。

安装 mkdocs

pip install mkdocs

当然也可以使用 apt，brew，cherry等工具装。

Get Started

使用如下命令创建一个文档工程,

mkdocs new <project name>

mkdocs运行主要需要两个部分：

• 一个yml配置文件用来进行配置
• 一个存放markdown文件的地址

在这里 mkdocs 生成了一个 docs 文件夹和 mkdocs.yml 配置文件

docs
mkdocs.yml

在这个路径下执行

mkdocs serve

可以通过 http://127.0.0.1:8000 访问生成的网页了。

简单配置

mkdocs会默认将 docs 文件夹下的 index.md 或者 readme.md 作为首页。同时，我们也可以通过自己的配置来决定页面布局。下面是一个完整的 mkdocs.yml

site_name: NAME

nav:
  - Home: index.md  
  - About: about.md
  - Other: other.md

theme:
    name: readthedocs

• site_name 网页的名字
• nav 导航栏
• theme 皮肤