Hugo+GitHub Pages架站教學

前言

以前還是窮學生時，玩過的架站管道有三個：

  1. 免費的線上架站平台(WordPress、Wix等)
  2. 自己開發的網站+免費虛擬主機服務提供平台(Free Hosting、Hostinger等)
  3. 自己開發的網站+本機電腦作為自架伺服器(使用XAMPP)

接下來是缺點排排站時間：

  1. 無腦使用UI就可以速成精美網站，但有損工程師的威嚴(嗎?)
  2. 主機服務多是國外提供，常常連線不穩還限制流量(94要錢啦)
  3. 本機的資安問題，還有電腦要一直開著(你關機伺服器就掛了啊啊啊)

綜合以上幾點，終於在最近決定也來透過GitHub佈署自己的靜態網站，並選擇號稱世界上最快的網站生成框架Hugo。下面就是我安裝的心路歷程啦！順便把中途遇到的疑難雜症跟解法記錄下來，希望也可以幫助到其他人囉 XD

前置作業

Christine’s Memo：

因為我的作業系統是Windows10，所以才寫cmd，總之需要任一種可輸入指令對電腦進行操作的CLI(command line interface)。程式開發軟體則依個人習慣啦~你硬要用記事本我也是不反對畢竟記事本萬能(?)

建置歷程

➤ 安裝Hugo

  1. 依自己的作業系統版本到官網提供的載點下載安裝包。
  2. 將下載的zip解壓縮，沒意外應該有三個檔案(hugo.exe、LICENSE、README.md)。
  3. 將解壓後檔案所在的資料夾路徑加到環境變數中。
  4. 在cmd輸入下面指令可確認是否安裝成功。
hugo version

Christine’s Memo：

將資料夾路徑加到環境變數中是要確保之後可順利使用Hugo相關指令，加環境變數的方法依系統而異，問Google就可以囉！補充一下，資料夾路徑就是你用檔案管理員打開資料夾後，上面方框中的C:\Users\blablabla那段，無腦複製就可以了

➤ 建立網站檔案

  1. 找好欲放置網站檔案的資料夾路徑(後續將稱其為網站根目錄)，並輸入下面指令。
hugo new site 網站根目錄
  1. 到該路徑下確認是否成功建立檔案，資料夾結構可能如下：
  • archetypes：
    存放markdown文件中前置數據Front Matter定義的結構(透過hugo new指令生成的markdown文章檔案會默認以default.md為格式基底)
  • content：
    存放全站內容的markdown文件
  • data：
    存放資料檔案(如JSON)
  • layouts
    存放自定義的樣板檔案(建置時若layouts中無檔案，則會使用themes中的)
  • public
    存放建置完成的最終檔案(部屬到GitHub Pages的部分)
  • static
    存放靜態檔案(如CSS、JS、IMG)
  • themes：
    存放已下載的主題檔案包
  • config.toml：
    存放全站的參數設定文件

➤ 安裝Hugo主題

  1. 到主題網站找到喜歡的主題，然後執行下面指令來切換到themes資料夾。
cd 網站根目錄\themes
  1. 在線上的主題介紹頁中按下Download的按鈕，然後將該連結頁面的網址複製下來，輸入下面指令來抓取主題。
git clone 複製的主題下載網址
  1. 到themes資料夾確認是否成功下載了主題檔案。

➤ 建立第一個頁面

  1. 在網站根目錄輸入下面指令，建立第一個頁面。
hugo new about.md
  1. 到content資料夾中確認是否成功建立了about.md，打開該檔案可對頁面進行部分設定(依各主題設計有所不同)。

➤ 建立第一篇文章

  1. 建議將文章放置於同一資料夾進行管理，因此可在網站根目錄輸入下面指令來建立新文章。
hugo new post/firstpost.md
  1. 在網站根目錄確認是否成功建立了post資料夾及firstpost.md，打開該檔案可對文章內容進行設定跟撰寫。

➤ 預覽網站

  1. 在網站根目錄輸入下面指令，Hugo會根據設定檔(.md)自動建置出實體html檔放於public資料夾中(預設)。
hugo

Christine’s Memo：

我在執行過程中有發生錯誤，訊息為「found no layout file for “HTML” for “section”: You should create a template file which matches Hugo Layouts Lookup Rules for this combination.」，後來把themes中layout資料夾內的所有檔案手動貼到網站根目錄下的layout資料夾內，才終於解決了問題

  1. 在網站根目錄輸入下面指令，即可透過瀏覽器預覽網站。
hugo server
  1. 於瀏覽器輸入http://localhost:1313/(預設)查看頁面。

Christine’s Memo：

我在預覽頁面時發現，所見的內容並非我在.toml設定的，也沒有吃到CSS/JS等檔案，執行hugo -v指令才知道config.toml中有個屬性是"publishDir"，而他的值並不是"public"，因此產出的完整檔案都沒有放到"public"資料夾中，以致我看到的頁面是有問題的，後來手動改為publishDir = “public"才解決問題

➤ 部署到GitHub

  1. 登入你的GitHub帳號，建立一個新的Repository，並命名為「你的使用者名稱.github.io」。

Christine’s Memo：

例如我的GitHub使用者名稱為Christine590，就一定要輸入「Christine590.github.io」喔

  1. 切換到欲作為本機Repository存放處的資料夾
cd 欲作為本機Repository存放處的資料夾路徑
  1. 如果是初次使用，需要先設定使用者名稱及電子郵件。
git config --global user.name 你的使用者名稱
git config --global user.email 你的電子郵件

Christine’s Memo：

若已安裝Git但在cmd輸入時顯示"不是內部或外部指令”，代表你需要把git-core所在的資料夾路徑加到環境變數中，特別注意加完之後要重開cmd才會生效喔

  1. 將GitHub上建立的Repository複製一份到本機端。
git clone https://github.com/你的使用者名稱/你的使用者名稱.github.io.git
  1. 切換到public資料夾中(因為public資料夾中的檔案才是建置完成的可預覽靜態檔案)。
cd 網站根目錄\public
  1. 將網站的內容部屬到GitHub Pages。
git add -A
git commit -m "本次版本異動的註解(也就是commit)"
git push origin master

Christine’s Memo：

執行git add指令前必須切換到「你的使用者名稱.github.io」那個Repository，不然上面指令可能會執行失敗，此時可以先試試下面的指令，完成後再重新執行一次步驟6的指令

git init  
git remote add origin https://github.com/你的使用者名稱/你的使用者名稱.github.io.git
  1. 於瀏覽器上輸入https://你的使用者名稱.github.io/就可以看到完整的個人主頁囉！

後續維護

➤ 編輯文章/修改樣版/新增資源檔

  1. 在進行調整後，若想預覽結果，依序執行下列指令即可。
cd 網站根目錄
hugo
hugo server

Christine’s Memo：

因Hugo支援熱部署(livereload)，修改文章或是更新css的話，刷新頁面即可看到效果，不需要重新建置喔

➤ 更新至GitHub Pages

  1. 若要將更新後的檔案部屬到線上，依序執行下列指令即可。
cd 網站根目錄
git add -A
git commit -m "本次的變更說明"
git push -u origin master

後記

關於Hugo還有很多應用，本篇只先講解了建置個人網站的方法，有興趣的版友可再自行研究下列議題喔！

  1. 在個人網站埋設數據追蹤碼，可到Google Analytics申請個人免費帳號
  2. 顯示主站或每篇文章瀏覽量，可使用不蒜子
  3. 新增文章分類、文章標籤、系列文章等註記
  4. 讓GitHub Pages可以被搜尋引擎索引及相關SEO作法
  5. 自動化部屬至GitHub Pages的實作方式