2018-12-24

使用MKdocs搭建个人博客并发布在Github Pages上

MKdocs安装

1. 首先需要在本地计算机安装python环境和pip工具

2. 使用pip下载Mkdocs库，执行：

   pip install mkdocs

3. 在本地任意路径位置创建文档项目，执行：

   mkdocs new <project name>

   执行完成后会在本地会生成一个以project命名的文件夹，此文件夹中包含站点所有文件信息

4. 尝试开启可用浏览器打开的本地站点，在该文件夹上执行：

   mkdocs serve

   站点开启成功后会的提示站点默认地址为：https://127.0.0.1:8000

   在浏览器上打开此地址会进入站点

将站点部署到Github上

1. 首先需要说明的是网上有关在本地Github仓库使用命名mkdocs gh-deploy将站点文件夹同步到Github的方法并不能直接访问。原因是GitHub Pages只能从master branch构建，而在本地仓库使用命令mkdocs gh-deploy只会在线上仓库另外生成一个名为gh-deploy的分支，因此无法实现使用https://<用户名>.github.io访问，因此还需要每次更新本地仓库后手动使用git命令将本地仓库同步到线上

2. 首先github官网上以<用户名>.github.io建立线上仓库

3. 在本地合适的位置使用命令clone线上仓库到线下，执行：

   git clone https://github.com/<用户名>/<用户名>.github.io.git

4. 在之间使用Mkdocs安装的本地文档项目文件路径文件夹上生成站点文件，执行：

   mkdocs build

   执行成功后会在本地文档项目文件夹中生成一个名为site的文件夹，site文件夹就是通过mkdocs编译生成的包含index.html的可被浏览器直接打开的静态前端站点

5. 进入site文件夹，将文件夹里的文件拷贝到git本地仓库中

6. 在本地git仓库先后执行git add -A git commit -m <commit words> git push将本地仓库中的文件同步到github的master branch上

7. 此时通过https://<用户名>.github.io域名就可以访问到mkdocs静态网页站点

8. 使用这种方法每次更新本地站点文件需要手动同步一次到github上。

使用个人域名打开Github Pages

1. Github自带的Pages地址过长，如果需要使用个人域名打开个人Mkdocs文档，可以在以上部署Github部署完成后执行如下操作

2. 首先需要知道个人Github Pages的IP地址，在本地终端中，执行：

   ping <用户名>.github.io

   执行后会得到IP地址

   ps：使用cmd+C可以退出ping命令，否则终端会一直执行ping的操作

3. 配置域名解析。在域名运营商网站工作台中配置域名解析，添加记录如下：

   主机记录	记录类型	线路类型	记录值
   www	CNAME	默认	<用户名>.github.io.
   @	A	默认	步骤1中得到的IP地址

4. 配置Github pages中Settings中的Custom domain填入域名，如example.com，并保存。

5. 完成配置，此时可使用域名example.com访问Mkdocs文档。