使用giteemkdocsreadthedocs搭建个人免费博客

　　使用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小时后，再访问。