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