使用MKdocs搭建個(gè)人博客并發(fā)布在Github Pages上

MKdocs安裝

1. 首先需要在本地計(jì)算機(jī)安裝python環(huán)境和pip工具

2. 使用pip下載Mkdocs庫(kù)，執(zhí)行：

   pip install mkdocs

3. 在本地任意路徑位置創(chuàng)建文檔項(xiàng)目，執(zhí)行：

   mkdocs new <project name>

   執(zhí)行完成后會(huì)在本地會(huì)生成一個(gè)以project命名的文件夾，此文件夾中包含站點(diǎn)所有文件信息

4. 嘗試開啟可用瀏覽器打開的本地站點(diǎn)，在該文件夾上執(zhí)行：

   mkdocs serve

   站點(diǎn)開啟成功后會(huì)的提示站點(diǎn)默認(rèn)地址為：https://127.0.0.1:8000

   在瀏覽器上打開此地址會(huì)進(jìn)入站點(diǎn)

將站點(diǎn)部署到Github上

1. 首先需要說明的是網(wǎng)上有關(guān)在本地Github倉(cāng)庫(kù)使用命名mkdocs gh-deploy將站點(diǎn)文件夾同步到Github的方法并不能直接訪問。原因是GitHub Pages只能從master branch構(gòu)建，而在本地倉(cāng)庫(kù)使用命令mkdocs gh-deploy只會(huì)在線上倉(cāng)庫(kù)另外生成一個(gè)名為gh-deploy的分支，因此無法實(shí)現(xiàn)使用https://<用戶名>.github.io訪問，因此還需要每次更新本地倉(cāng)庫(kù)后手動(dòng)使用git命令將本地倉(cāng)庫(kù)同步到線上

2. 首先github官網(wǎng)上以<用戶名>.github.io建立線上倉(cāng)庫(kù)

3. 在本地合適的位置使用命令clone線上倉(cāng)庫(kù)到線下，執(zhí)行：

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

4. 在之間使用Mkdocs安裝的本地文檔項(xiàng)目文件路徑文件夾上生成站點(diǎn)文件，執(zhí)行：

   mkdocs build

   執(zhí)行成功后會(huì)在本地文檔項(xiàng)目文件夾中生成一個(gè)名為site的文件夾，site文件夾就是通過mkdocs編譯生成的包含index.html的可被瀏覽器直接打開的靜態(tài)前端站點(diǎn)

5. 進(jìn)入site文件夾，將文件夾里的文件拷貝到git本地倉(cāng)庫(kù)中

6. 在本地git倉(cāng)庫(kù)先后執(zhí)行git add -A git commit -m <commit words> git push將本地倉(cāng)庫(kù)中的文件同步到github的master branch上

7. 此時(shí)通過https://<用戶名>.github.io域名就可以訪問到mkdocs靜態(tài)網(wǎng)頁(yè)站點(diǎn)

8. 使用這種方法每次更新本地站點(diǎn)文件需要手動(dòng)同步一次到github上。

使用個(gè)人域名打開Github Pages

1. Github自帶的Pages地址過長(zhǎng)，如果需要使用個(gè)人域名打開個(gè)人Mkdocs文檔，可以在以上部署Github部署完成后執(zhí)行如下操作

2. 首先需要知道個(gè)人Github Pages的IP地址，在本地終端中，執(zhí)行：

   ping <用戶名>.github.io

   執(zhí)行后會(huì)得到IP地址

   ps：使用cmd+C可以退出ping命令，否則終端會(huì)一直執(zhí)行ping的操作

3. 配置域名解析。在域名運(yùn)營(yíng)商網(wǎng)站工作臺(tái)中配置域名解析，添加記錄如下：

   主機(jī)記錄	記錄類型	線路類型	記錄值
   www	CNAME	默認(rèn)	<用戶名>.github.io.
   @	A	默認(rèn)	步驟1中得到的IP地址

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

5. 完成配置，此時(shí)可使用域名example.com訪問Mkdocs文檔。