Github Pages是 Github 的一個免費靜態網頁托管服務。可以用來做個人部落格，項目簡介 / 文檔，組織官網（如實驗室官網）等。本文將詳細介紹 Github Pages 的使用方法（其實步驟非常簡單，最快 10 分鐘就可以起一個網站）。開始前先進一段簡介，也可以直接跳到做項目首頁和個人部落格的具體步驟。
Pages 簡介#
Pages 的優點是不需要配伺服器，資料庫這些環境，簡單，穩定，免費。這使得 Pages 很適合做個人部落格，項目首頁，企業官網這一類純展示性質（可能也不產生收益 😂）的站點。其缺點是只能托管靜態網頁，意思是對於每個訪問者網站展示的內容都是一樣的。這不意味著 Pages 裡不能有任何動態的元素，比如可以結合 Issue 或 Discussion 實現部落格評論。但是要做功能複雜的網站（比如帶登錄的）或者有複雜的資料處理，大概還是有一個伺服器後台會更方便。
Pages 在項目每次更新後會做兩件事：
- 將項目中的 Markdown 用 Jekyll 轉成網站
- 托管這個網站
因為 Jekyll 只會根據一些配置文件處理 Markdown 文件，所有的網頁都會原樣保留，所以也可以直接往項目中推構建好的網站，只是白嫖一下托管。這種方案可以用任何方式，比如hexo和hugo，過程和用 Jekyll 本地構建後直接上傳網站相同。
總結起來用 Pages 主要有三種姿勢
- 上傳 Markdown，直接讓 Pages 用 Jekyll 構建成網站托管
- 上傳 Markdown，用 Github Action 構建成網站托管
- 直接上傳網頁，讓 Pages 托管
這三種方法操作複雜度和靈活性都是依次遞增。
- 第一種方式最簡單也很方便，但是 Pages 的 Jekyll 只提供了13 個為項目首頁設計的單頁主題，所以通常也只有項目首頁用第一種方式。
- 個人部落格和組織官網用第二種的居多，直接 Fork 一個主題項目就行，夠靈活而且不用本地配環境，Action 的構建腳本通常 Jekyll 主題都自帶，不需要操心自己寫。
- 直接上傳網頁靈活性最高，不過大多數場景下感覺沒有必要。除非是沒用 Jekyll 這種工具生成網頁，而是自己直接寫的網頁，否則感覺第二種方法就夠用了。
Github#
這段面向之前完全沒用過 Github 和 git 版本管理工具的讀者，簡單說說如何註冊 Github，創建項目和 git 是什麼。
Github 是一個代碼托管平台，開發者把代碼上傳到這個平台上，方便一個項目的多個開發者同步代碼，同時也有助於開源項目的傳播。註冊需要一個郵箱，訪問Github 註冊頁面，按提示操作就行。
Github 上的項目可以自己新建也可以複製別人的，就做部落格來說直接複製主題項目比較多。Fork 的意思就是將別人的一個項目複製一份，存到自己的 Github 賬戶下。在每個項目的右上角都有一個 Fork 按鈕
點擊之後就會跳轉到一個自己的新項目，項目的內容和名稱都和原來的項目一樣。這個項目已經在自己的賬戶下，可以進行修改。
如果是要創建自己的項目，點首頁左邊一個綠色的創建新項目（New）按鈕就行。
一般建議添加一個 README.md，空項目是沒法直接從 Github 往下拉的，需要本地跑幾行操作，稍微麻煩一點。
git 是一個代碼版本管理工具，簡單來說可以讓你在寫代碼過程中創建一些存檔點。如果只有一個開發者那麼這些存檔點大概就是一條直線，一個比一個新，像下面圖裡的紅線。如果有多個開發者同時對項目做修改，存檔點可以有一些平行的路徑，像下面圖裡的藍線和黃線。就做個人部落格來說不需要了解很多的 git 知識，操作也不需要命令行，有很多帶界面的 git 軟件比如Github Desktop和gitg。做部落格最簡單的方法是 Fork 一個主題項目，將項目 pull 到本地，進行修改，之後再將修改 push 到 Github 上。後面用到的時候會說具體怎麼操作。
項目首頁#
從最簡單的開始，先介紹怎麼做項目首頁，也就是怎麼用 Pages 直接把 Markdown 變成一個能訪問的網站。首先打開一個 Github 項目，點進 Settings->Pages 頁面。一個沒開啟 Pages 的項目應該是這樣的
Source 這裡選 Markdown 所在的 Branch
後面的文件夾選項是指定在這個 Branch 下去哪找 Markdown 文件。如果只在根目錄下有一個 README.md 的話保持默認 /(root) 就行，如果文檔是分成多個文件可以都放到 docs 文件夾下，選擇 /docs。
保存。
稍等一會訪問上面這個網址就能看到網頁了。Pages 用一個 Enviroment 進行靜態網站生成和托管，查看進展的方法是首先回到項目首頁
在右下角可以看到一個 Enviroments，點進那個 github-pages
就可以看到部署的執行情況，刷新幾次就會看到一條新的部署記錄，點 view deployment 就會跳轉到網頁了。
默認部署沒有主題看起來大概比較素，可以在 Settings -> Pages -> Theme Chooser -> Choose a theme 這裡選一個主題。
點擊之後會看到主題的預覽，點 Select Theme 選中一個主題。
這個時候 Pages 會在代碼裡創建一個_config.yml 文件，記下你選的主題。內容類似這個
等一會 Pages 更新之後就能看到帶主題的網頁了。
Pages 給了 13 個主題，做項目首頁的話不建議用這 13 個之外的。Pages 的文檔中描述了怎麼使用外部主題但是 Pages 的 Jekyll 環境比較簡單，很多主題都會缺 gem 依賴，而且部署過程貌似也沒有詳細的 log，出問題了大都跟下面一樣只有一句構建失敗，不太好 debug。
想用第三方主題建議用 Action 創建一個環境編譯。
個人部落格#
下面就到了這篇的重頭戲，用 Pages 部署個人部落格。過程非常簡單，選一個主題，用 Jekyll 或者類似工具（如hexo，Octpress）把 Markdown 構建成 html，之後推到 Github 項目中就完成了（個人只用過 Jekyll 所以下文也是針對 Jekyll 寫的，但用其他工具的流程也是一樣的）。構建的這一步通常用 Github Action，非常方便，搭建的過程 10 分鐘就能搞定。本地構建麻煩一些，但是靈活度高，下文將分別介紹。
主題#
如果是前端大佬大可以用 html，css，js，liquid 這些語言自己搞一個主題，不過 Jekyll 有很豐富的主題生態可以即 Fork 即用。選擇主題的指導原則是好看和好用。好看純看個人審美，沒什麼好說的。好用是希望主題的功能盡可能豐富。一些常見的功能包括：
- 部落格內搜索
- 自動生成 sitemap：便於搜索引擎收錄，搜索引擎大概會是部落格最主要的流量來源
- 文章標籤和分類：部落格首頁一般都按發表順序展示文章，內容多了之後標籤和分類會比較實用
- 文章目錄 TOC：長文用的上
- 發表時間，修改時間：發表時間一般都是有的，修改時間要看 git 記錄，不是所有主題都有
- 深色模式
- 代碼塊
- 數學公式
- ...
這些功能主題就算沒有也都可以自己加，不過主題帶的話可以省很多麻煩。主題一般都是 Github 項目，質量高的通常 Star 和 Fork 數比較多，更新頻率高。好的主題一般教程詳細，部署過程中也不容易出問題。
本文以我正用的Chirpy為例，更多的主題可以逛逛下面這些網站
推薦 Fork 主題，優點是用 Github 最近出的 Fetch Upstream 跟著上游更新主題比較方便。
Fork 項目之後需要按照 用戶名.github.io 格式改項目名，比如我 Github 用戶名是 linhandev，那項目名就是 linhandev.github.io。點 Settings 第一個設置就是。
如果名字衝突要刪之前的部落格千萬千萬記得保存內容，之前丟過好幾波寫好的文章。。。佔名字的項目也不需要刪，改個名字就行。
看一看主題的 README 對使用方法的介紹，一般都會仔細的寫 Fork 之後需要進行哪些操作，比如 Chirpy 會需要運行一個腳本。看文檔雖然無聊，但絕對比出問題之後一通 debug 節省時間。謀定而後動，最近面試感覺自己這方面差很多。
Jekyll 的主要設置都在根目錄下的 _config.yml 文件裡，比如網站標題 title ，副標題 tagline，時區 timezone，頭圖 avatar，和一些社交媒體配置之類的。走一波這個文件，一般都有註釋每個設置是啥，把想改的改一改。
Action 構建#
Action 寫起來稍微複雜，不過大多數主題要麼自帶用 Action 構建的腳本，要麼可以直接用 Pages 的環境構建。寫這部分的目的主要在於方便在部落格構建失敗的時候 Debug，以後可能會更新這個 Action 具體怎麼寫。如果主題沒提供這個腳本，自己對 Action 也不熟悉的話，那本地構建會更簡單。
Github Action 會在項目有一些動作之後觸發，比如 push，開 Issue 之類。Action 的配置在項目的 .github/workflows 文件夾下。首先一定看一下主題 README.md 裡有關開始使用的部分，一些主題會有一個初始化的腳本，之前用 Chirpy 的時候就因為沒仔細看文檔走了一堆彎路。
每次 push 更新之後 Action 會自動執行，在項目的代碼頁面 commit 的左邊會有一個圖標，就是下圖紅框的位置
Action 執行過程中是一個黃點，執行成功是一個綠色的對號，如果看到一個紅叉就是執行出問題了。執行成功之後點代碼左上角的下拉菜單看看是不是多出一個 branch
修改 Settings->Pages 裡的設置，將 Source 改成這個 branch
如果 commit 左邊圖表是紅叉可以看一下 Action 執行的 log 來排查具體是什麼問題。
- 點項目上面的 Action 能看到所有的執行
- 點進其中的一次執行是這樣
- 點在那個 continus-delivery 位置的按鈕（不一定叫一個名字）可以看到具體的執行 log。
展開出錯的部分就可以看到具體是什麼問題了。
第一次執行 Action 需要創建環境，下一堆依賴應該會比較慢，可能要幾分鐘。Chirpy 的 Action 腳本會緩存 Ruby 的環境，以後每次執行大概只需要半分鐘。Action 執行成功後 Pages 還需要幾分鐘才會更新，只要 Action 執行成功了這次發布就沒什麼問題，等著就行。
本地構建#
使用 Action 構建很方便，主要的缺點是每次 push 之後需要等上幾分鐘才能看到效果。一般這沒什麼，但如果遇到一些問題需要反復編譯去 debug 的時候也會讓你一通好等。本地跑 Jekyll 可以實時編譯，保存之後刷新網頁就能看到更新。
安裝環境#
Jekyll 用 Ruby 編寫，本地運行需要裝 Ruby 和 Ruby 的包管理工具 RubyGem，這裡列一下 Arch Linux 的安裝步驟，其他系統可以參考官方安裝文檔
sudo pacman -S Ruby base-devel
安裝的過程中遇到個小問題，pacman 下清華源幾個文件一直失敗。解決的方法是上清華源的網站，直接下載對應的安裝包文件之後 pacmsn -U 安裝。裝好 Ruby 之後換源，之後裝 jekyll，bundle
# 添加清華源並移除默認源
gem sources --add https://mirrors.tuna.tsinghua.edu.cn/Rubygems/ --remove https://Rubygems.org/
gem sources -l # 列出所有源，應該只有TUNA一個
gem install jekyll bundler # 裝包
bundle # 讓bundle安裝jekyll的依賴
jekyll # 測試安裝是否正確
# 頭兩行輸出應該是
# A subcommand is required.
# jekyll 4.2.1 -- Jekyll is a blog-aware, static site generator in Ruby
如果上面最後一行輸出的是找不到 jekyll 命令，那應該是可執行文件路徑裡沒有 gem 中的 bin 文件夾，仔細看看gem install命令的輸出應該針對這個問題有提示，把 bin 的路徑添加到 PATH 裡就行。
gem environment # 找輸出的GEM PATHS部分
export PATH=$PATH:[上面的gem path] # 比如Arch上是 /usr/lib/Ruby/gems/3.0.0
jekyll # 試試改的對不對
# 如果能找到命令了就把這行寫到 ~/.bashrc 裡，這樣打開一個新命令行依舊有效
echo 'export $PATH=$PATH:[上面的gem path]' >> ~/.bashrc # 必需單引號，雙引號會用值替代變量
到這 Jekyll 的環境應該就配置好了，下一步進行構建和 push。
構建和 push#
首先把 Github 上的項目 clone 到本地，創建新項目或者 Fork 主題，項目名要求是 Github 用戶名.github.io 這些前面已經說過了。如果創建新項目添加一個空的 Readme 方便後面 clone。完成後把項目 clone 到本地。
git clone https://github.com/[username]/[username].github.io
cd [username].github.io # 進到項目裡
如果是新項目將主題的所有文件放到項目裡。應該有_config.yml，index.html，_post 之類的一堆文件和文件夾。
這個時候就可以本地構建了
jekyll build # 構建結果在_site文件夾裡
# 或者
jekyl b # b是簡寫，效果是一樣的
此外還可以起一個本地的服務展示部落格，每次 Markdown 文件保存後網站都會自動重新構建，刷新頁面就能看到修改
jekyll serve # 之後訪問 Server address: 那個網址就能看到
# 或者
jekyll s # 簡寫
構建成功之後給構建出來的網頁文件單獨創建一個 branch。下面的腳本有刪除的代碼，一定確定好自己在哪個 branch 上，否則可能誤刪 Markdown 文件。
git branch # 查看一下當前分支叫什麼，一會還要回來
git branch gh-page # 創建 gh-page branch
git switch gh-page # 切換到新branch
git rm -r * # checkout會把原來分支的所有文件都帶過來，刪掉它們
git commit -m "clean up"
git push --set-upstream origin gh-page # 推到 Github上
git checkout main # 返回之前的branch
分支創建完成了，build 並推到 Github 上。
# 在主分支構建
git switch main
jekyll build # md轉html
# 將 _site 中生成的html網站放到 gh-page 分支的根目錄裡
git switch gh-page
mv _site .site
rm -rf *
mv .site/* .
rm -rf .site
ls # 應該有404.html，main.html這樣的文件
# 在 gh-page 分支 push
git add *
git commit -m "Update Blog"
git push
# 返回 main 分支 push
git switch main
rm -rf _site
git add *
git commit -m "Update Jekyll Blog"
git push
到這複雜的部分基本就完成了，最後跟前面一樣改一下 Pages 的 Source。到 Github 項目的 Settings->Pages 裡，將 Source 設成 gh-page，/root，保存。
等幾分鐘網站應該就可以訪問了。
部落格評論#
你可能希望大家在看完部落格之後給點反饋。文章評論不是一個靜態的功能所以光靠 Github Pages 實現不了。我了解到的方案主要是兩類
- 用自己搭建的或第三方的評論服務
- 用基於 Github Issue 或 Discussion 的方案
最開始我是用的第三方評論服務hyvor，當時試運營是免費的但是現在已經收費了。這種服務套餐的量一般都很大，比如 hyvor 起步的 $5 / 月套餐就有 10w page view。估計我有生之年部落格都不會有這麼大的流量。😂
Github 的服務依舊更加良心。😂 這一類的項目有很多，一些主題可能對其中的一些有內置的支持，比如 Chirpy 就內置了對 disqus，utterances（基於 Issue）和 giscus（基於 Discussion）的支持。這類方案的主要的缺點是貌似所有的項目都需要用戶 Github 登錄之後才能評論，一些還會需要用戶 OAuth 授權。
目前用的是 utteranc，就以它為例，其他的也都差不太多。
utteranc 會給每篇文章創建一個 Issue，用戶對文章的評論會保存為 Issue 下的回覆。評論的時候會需要用戶用 Github 賬戶登錄，之後授權 utteranc。
安裝過程很簡單
- 訪問這個網址，在 Gtihub 上安裝 utterances app
可以只給部落格一個項目的權限
- 安裝完成後會打開utteranc 網站，按照引導進行設置，先寫項目名
- 選擇每篇文章 Issue 的格式
這裡要注意 utteranc 會按照配置的格式去找文章對應的 Issue，基本上是根據文章的標題或者 Markdown 文件名。如果修改了文章的標題或者 md 文件名也需要修改對應 Issue 的名字，否則就找不到任何評論。個人感覺設第一個是最好的，文件名估計不會有文章名改的多。
- 之後可以填一個 utteranc 創建 Issue 的標籤，作用不大
- 最後選擇一個和主題視覺協調的配色
下面能看到一段代碼，把它插入到文章模板裡正文下面的位置就可以用了。Chirpy 的文章模板是在 _layouts/post.html，別的主題也都類似。最後的效果
本地編輯環境#
Markdown 不是所見即所得，而且插入圖片一般有點費勁。本地環境可以很好地解決這些問題，簡化寫作流程。個人很喜歡 Atom，在另一篇文章中記了如何配置 Atom 寫 Markdown，可以參考。
搜索引擎收錄#
一般個人部落格的流量都不大，Chirpy 主題的作者甚至不推薦大家開文章瀏覽量功能，怕打擊博主的創作熱情 😂 不過如果你的部落格有一些高質量的內容，搜索引擎是可以帶來一些流量的。
搜索引擎優化是一門學問，但如果只是很佛系的告訴搜索引擎：“我有個網站，你爬不爬看著辦”，那只要添加 robots.txt，之後提交一個 sitemap 就行。
sitemap 可以看作網站的地圖，告訴爬蟲我這個網站都有些什麼頁面可以訪問。大多數主題都會帶這個功能，訪問 [github id].github.io/sitemap.xml ，如果不是 404 那就是有 sitemap 的。比如我的長這樣
如果你的主題不帶 sitemap 也可以自己添加
robots.txt 是用來告訴搜索引擎網站上哪些網頁該爬，哪些網頁不該爬的。可以訪問 [github id].github.io/robots.txt 看看自己有沒有這個文件。如果沒有的話，在項目根目錄中加上一個 robots.txt 文件就行，一個最簡單的寫法是
User-agent: *
Disallow: /norobots/
Sitemap: https://[github id].github.io/sitemap.xml
{: file='robots.txt'}
這個文件告訴搜索引擎所有類型的爬蟲都可以爬這個網站，除了 /norobots/ 路徑下的所有頁面都可以爬取和網站的 sitemap 在哪。
robots.txt 和 sitemap 俱全就可以向搜索引擎提交網站了。這裡需要用到各大搜索引擎的站長工具，webmaster 或者 search console。下面是一些常用的搜索引擎站長工具鏈接。
提交的過程類似：
- 註冊帳號
- 證明網站是你的
- 提交 sitemap
證明這一步通常有多種方法，對於 Pages 來說最方便的應該是添加文件。只需要將文件下載下來扔到項目根目錄下，之後把修改推上 Github 就行。注意這個文件要放在構建前的有 Markdown 目錄而不是構建出來的網頁目錄，否則重新構建會把這個文件抹掉。
第二種常用的方法是在網站 header 中加入 meta tag，這種方法的優點是添加多個搜索引擎的話項目的根目錄整潔一些（如果這可以算優點的話）。tag 的內容是一串隨機字符。比如我的 bing 搜索驗證 tag 是
<meta name="msvalidate.01" content="D657F7EB150CC9886DA47F92C4D34ED6" />
在 Chirpy 主題中網站的 header 部分在 _includes/head.html 定義，如果你的主題目錄結構不一樣可以在項裡搜一下 head 開頭的文件。找到之後這行代碼放到 head.html 的 head 部分就行了。
驗證身份後找帶 sitemap 的 tab，點進去輸入 sitemap 網址就大功告成了。就我這個網站添加多個搜索引擎之後不多的流量來看，bing 國內版似乎是對新網站最友好的，大概提交 sitemap 3 4 天之後就能看到來自 cn.bing.com 的流量。Google 也有一兩個，其他國內的搜索引擎大多數連爬都懶得爬。
流量統計#
換位思考，我不想被別人統計所以也不做流量統計。
自定義域名#
Pages 的默認網址是固定的，比如個人部落格都是 用戶名.github.io，項目網站都是 用戶名.github.io/ 項目名 。但是 Pages 也支持自定義域名。
要用自定義域名非常明顯首先要自己有一個域名，這個在各大雲廠商都能買到，大概的過程是
就可以了。價格跟很多因素有關，比如域名長度，頂級域名是什麼，買多久之類的，大概每年幾十。如果不想花錢也可以到Freenom申一個免費的。
在域名解析的後台將這個域名 CNAME 解析到 用戶名.github.io，之後在項目的 Settings -> Pages 裡面填寫自己的域名。這個時候 gh-page branch 裡會多一個 CNAME 文件，本地注意 pull 一下否則會衝突。在 main 分支的根目錄裡也加入這個文件。之後就可以使用自己的域名訪問了。
之前從自定義域名轉換回 Github 給的免費域名過程中遇到一點麻煩，輸入免費域名總是直接跳轉到之前解析的自己的域名，之後頁面顯示 Github 的 404。這種情況清一下瀏覽器的 cache 就好了。
結語#
到這基本上 Github Pages 的基本用法就介紹完了。這篇文章還會不斷更新進行更正和豐富。如果使用過程中有任何問題也歡迎在下方評論留言。