1 什么是MkDocs
MkDocs---markdown项目文档工具，是一个用来创建项目文档的快速、简单、完美的静态站点生成器，文档源码使用Markdown来撰写，用一个yml文件作为配置文档。它具有如下几个优点：
1.1 任意托管
构建完全的静态 HTML 站点 , 可以将它托管到 GitHub pages, Amazon S3 等任意地方。
1.2 大量主题
默认包含大量美观的主题。可以从 bootstrap, readthedocs 和 12 款 bootswatch 主题中选择。
1.3 即时预览
内建的开发服务器使你在撰写文档的时候就即时预览. 它甚至能在保存更改时自动载入, 只需刷新浏览器就可以查看更改。
1.4 易于配置
可以配置文档主题。
1.5 交叉索引
使用MkDocs链接语法创建交叉索引。
2 什么是Materialfor MkDocs
一个MkDocs的MaterialDesign主题。(A Material Design theme for MkDocs )Material 是MkDocs的主题，是针对项目文档的优秀静态网点生成器。它是基于Google的Material Design 指南搭建的。
3 安装
因为mkdocs是基于python对markdown的文档生成器，安装mkdocs之前得先安装python。
3.1Mkdocs安装
pip install mkdocs |
3.2Material for MkDocs安装
pip install mkdocs-material |
3.3环境配置
要在cmd上运行mkdocs还需要配置系统环境，控制面板-集团和安全-系统-高级系统设置-系统变量，找到path，添加mkdocs.exe的路径。其路径根据安装方法不同位置不同，pip安装的是在python安装目录下的scripts下。最后以管理员身份打开cmd，输入mkdocs没报错就是安装成功了。
4 用mkdocs创建静态网页
4.1项目创建
管理员模式打开cmd，输入
mkdocs new my-project cd my-project mkdocs serve |
生成一个my-project项目文件夹，里面有docs文件夹和mkdocs.yml配置文件，会给你一个预览网址默认是http://127.0.0.1:8000/，用默认浏览器打开它就可以看见网页。
4.2网页内容配置
因为mkdocs的即时预览，你修改的配置会直接载入网页。
用管理员模式下的cmd打开mkdocs.yml进行修改
site_name: MkDocs介绍及应用 /(网页名称) nav: /(添加次级目录) - Home: index.md /(主页) - Blog: mkdocs介绍.md /(其他页面) theme: /(网页主题) name: 'material' /(这就是我们安装的mkdocs-material) |
在次级目录下还可以创建目录。
nav: -Blog： -Blog1: xxx.md |
网页内容就是放在docs文件下的.md文件。
配置完后在my-project文件夹下用cmd输入
mkdocs build |
完成后会生成一个site文件夹，这个文件夹里的内容就是生成的静态网站。
5 结语
生成的静态网站可以部署到readthedoc和github上。团队可以用这个来管理博客和文档。因为不支持中文搜索，管理博客还是有一些问题的，主要还是用来管理文档的。
