谈一谈|MkDocs介绍及应用

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上。团队可以用这个来管理博客和文档。因为不支持中文搜索，管理博客还是有一些问题的，主要还是用来管理文档的。