使用mkdocs来管理自己写markdown文件，生成博客的方式，相比sphinx要简单、容易很多。但是，美中不足，就是生成的博客界面主题样式可选性相对较少，没有sphinx那么丰富，界面看上去没有那么美观。

简介

• gitee 是国内知名的代码托管平台，个人可以使用其免费版本。
• mkdocs，是一个用于创建项目文档的快速,简单,完美华丽的静态站点生成器. 文档源码使用 Markdown 来撰写, 用一个 YAML 文件作为配置文档.
• readthedocs，是一个免费在线文档托管范围平台，可以使用二级域名显示个人博客。

环境搭建

• 下载项目
• 配置环境
• 创建一个虚拟环境
• 安装mkdocs： pip install mkdocs
• 创建项目架构： mkdocs new docs

项目名称
|————mkdocs.yml
|————docs
	|————index.md

• 启动服务： mkdocs.exe serve (windows) 这样，就可以通过http://127.0.0.1:8000 访问项目了。
• 此时，使用的主题为默认的 readthedocs，可以自己安装主题，然后修改mkdocs.yml文件中theme的值。
• 如下载当下比较流行的material主题： pip install mkdocs-material 然后修改mkdocs.yml文件中的theme为‘material’
• 放置md文件
• 可以把写好的markdown文件放在docs文件夹下，也可以在docs文件夹下新建文件夹分类管理自己的md文件。
• 编辑mkdocs.yml文件
• 如果把md文件放在docs文件夹下，此时编辑mkdocs.yml文件，如：

nav:
 	- '首页': 'index.md'
 	- 节点2： 
 			- 'doc2': 'document-2.md'
 			- 'doc3': 'document-3.md'
 	- 节点3:
 			- 'doc4': 'document-4.md'

• 如果在docs文件夹下再建文件夹管理md文件，此时编辑mkdocs.yml文件，如：

nav:
 	- '首页': 'index.md'
 	- 节点2:
 			- 'doc2': '文件夹名/document-2.md'
 			- 'doc3': '文件夹名/document-3.md'
 	- 节点3：
 			- 'doc4': '文件夹名/document-4.md'

• 本地测试(可选)
• 这个事情，不是必须的，但是，如果本地没有测试通过，发布的时候，失败也是一个麻烦事情，所以，建议本地先测试通过。
• 执行： mkdocs serve 如果一切正常，就可以在本地使用 http://127.0.0.1:8000 访问，查看自己博客的效果。
• 如果自己对效果不满意，可以自行调整，或更改主题样式。
• mkdocs的主题样式，没有sphinx那么多样。
• readthedocs中导入项目
• 在导入readthedocs之前，需要把项目中安装的库生成到requirements.txt文件中。如：

mkdocs
mkdocs-material

• 上传已经通过自己验证之后的项目文件到gitee。build文件夹下的内容，可以不用上传。（github也是类似）
• 访问 www.readthedocs.org 网站，注册一个账户，登录
• 点击【导入一个项目】> 【手动导入】
• 填写项目名称、gitee的项目路径(不带.git)、默认分支(master)
• 注意： 这个项目名称将作为博客访问的readthedocs的二级域名，为了好记住，用英文，不要太长，与gitee上的项目名称没有关系，可以不同名。
• 在readthedocs中找到自己导入的项目的【构建】，点击【构建版本】，此时就会开始构建。
• 注意： readthedocs默认配置，构建项目时，会构建sphinx-HTML、PDF、EPUB 三种，如果你项目中的文档、图片较少，构建这三个没有问题。但是如果你项目文档、图片都比较大，可能会报错，可以在readthedocs项目的【管理】> 高级设置 中取消 PDF、EPUB的构建。
• 注意： 因为readthedocs是国外服务，在国内，可能也会出现访问慢或无法访问、或没有及时更新博客界面情况，只要构建成功，24小时后，再访问。