如何使用Hugo+Github架設網站

Posted on 2025-04-02 | Post modified | In Tutorial |

如何使用Hugo+Github架設網站

參考資料: 為了 SEO！我離開了 Medium，改在 GitHub 上自架個人網站

註冊Github Account & Create Github Page

參考資料: 使用 GitHub Pages 架設個人網站

(Optional)

參考資料: Github Pages 自訂網域教學

Hugo Step

參考資料: 使用 Hugo 在 github 部署個人網站

安裝Hugo(latest version)

在Github Release可以找到符合自己需求的版本，目前我是選0.145.0_windows_amd64
解壓縮到C:\hugo\bin

設定環境變數，設定完後測試

 $ hugo version
 hugo v0.145.0-666444f0a52132f9fec9f71cf25b441cc6a4f355 windows/amd64 BuildDate=2025-02-26T15:41:25Z VendorInfo=gohugoio

Deploy Website on Local

Create New Site

 $ hugo new site demo
 Congratulations! Your new Hugo site was created in D:/Life/Website/demo.

 Just a few more steps...

 1. Change the current directory to D:/Life/Website/demo.
 2. Create or install a theme:
     - Create a new theme with the command "hugo new theme <THEMENAME>"
     - Or, install a theme from https://themes.gohugo.io/
 3. Edit hugo.toml, setting the "theme" property to the theme name.
 4. Create new content with the command "hugo new content <SECTIONNAME>\<FILENAME>.<FORMAT>".
 5. Start the embedded web server with the command "hugo server --buildDrafts".

 See documentation at https://gohugo.io/.

選擇Hugo Theme並且更新toml File 到Hugo的Official Demo Theme看哪一個theme適合自己，假設我選擇relearn這個theme，就點選Download

 $ cd ./demo
 $ git submodule add https://github.com/McShelby/hugo-theme-relearn.git themes/relearn # 因為我是用relearn這個theme所以URL和folder name是customize
 # 也可以直接下載zip file，不過下面在設定toml file有一個地方要修改
 $ echo theme = 'relearn'>> hugo.toml # For CMD
 $ echo "theme = 'relearn'" >> hugo.toml # For linux

這個toml檔案就是一個config file，所以描述網站的最基本資訊

新增一個測試的檔案
1
2
3
4
5
6
7

$ hugo new posts/hello.md $ cat ./content/posts/hello.md +++ date = '2025-04-02T19:15:29+08:00' draft = true title = 'Hello' +++
hugo會在./demo/content/posts的地方新增一個hello.md這個檔案，並且把draft property改成false，最後deploy之後才會顯示

Deploy Local Server

 $ hugo server
 Watching for changes in D:\Life\Website\demo\{archetypes,assets,content,data,i18n,layouts,static,themes}
 Watching for config changes in D:\Life\Website\demo\hugo.toml, D:\Life\Website\demo\themes\relearn\hugo.toml
 Start building sites …
 hugo v0.145.0-666444f0a52132f9fec9f71cf25b441cc6a4f355 windows/amd64 BuildDate=2025-02-26T15:41:25Z VendorInfo=gohugoio


                    | EN
 -------------------+-----
   Pages            | 11
   Paginator pages  |  0
   Non-page files   |  0
   Static files     |  0
   Processed images |  0
   Aliases          |  0
   Cleaned          |  0
    
 Built in 163 ms
 Environment: "development"
 Serving pages from disk
 Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
 Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
 Press Ctrl+C to stop

現在Local的deployment已經完成，剩下的就是deploy到Github Page

利用Github Action Deploy Hugo

如果沒有碰過github action的人可能要先熟悉一下，這東西就是github的自動化流程，網路上有很多種action script，應該大同小異，我是用peaceiris/actions-gh-pages
1

$ mkdir .github/workflows && touch .github/workflows/gh-pages.yml
```
 name: GitHub Pages
    
 on:
   push:
     branches:
       - main  # Set a branch name to trigger deployment
   pull_request:
    
 jobs:
   deploy:
     runs-on: ubuntu-22.04
     permissions:
       contents: write
     concurrency:
       group: $-$
     steps:
       - uses: actions/checkout@v3
         with:
           submodules: true  # Fetch Hugo themes (true OR recursive)
           fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
    
       - name: Setup Hugo
         uses: peaceiris/actions-hugo@v2
         with:
           hugo-version: '0.145.0'
    
       - name: Build
         run: hugo --minify
         working-directory: ./demo
    
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
         # If you're changing the branch from main,
         # also change the `main` in `refs/heads/main`
         # below accordingly.
         if: github.ref == 'refs/heads/main'
         with:
           github_token: $
           publish_dir: ./demo/public
```
- on的意思是當main這個branches出現push的操作時，就要觸發這個workflow，也就是設定觸發條件的意思
- jobs就是說明要做的事情，具體要看jobs.deploy.steps的內容
  - 因為有使用到別人的themes，並且如果是使用submodule的方式加入到git的話，submodules這個property就要設定true，但如果是直接下載的話就要設定成false
  - 因為我是使用peaceiris的workflow script所以uses就不用改，但hugo version就要改成latest的版本，不然會不過，像我的就是0.145.0
  - Build minify的意思是透過hugo把指定資源進行最小化處理
  - Deploy就是使用peaceiris/actions-gh-pages@v3這個版本的script，進行deploy，不用管具體在幹麻，需要注意的是，publish_dir是在./demo/public，因為hugo會把我寫的所有文章rendering之後放到./demo/public這個folder，所以我設定一個條件，如果main這個branch有變化，就把./demo/public這個folder中的所有內容，透過script更新到gh-pages
設定Github的一些東西到自己設定的website repo首頁https://github.com/<username>/<username>.github.io，會看到上面有Actions和Setting兩個subpage 先到Setting > Pages 選擇Build and deployment中的選項為==GitHub Actions==，這個的意思是，因為Github在deploy類似Hugo這樣的靜態網頁框架時，如果選擇Deploy from a branch，那預設就會deploy Jekyll這個框架而不是Hugo導致deployment會失敗如果在VScode的GitHub Actions Extension發現有另外一個workflow叫做pages build deployment那大機率就是這個地方沒有設定好，可以參考禁用Github pages build deployment
Push to repo
1
2
3

$ git add . $ git commit -m "Init Website" $ git push
丟上去到repo的時候可以透過vscode的GitHub Actions這個Extension查看有沒有deploy成功有時候會出現像這樣deploy失敗的狀況，可以利用旁邊的View step logs查看具體哪邊出問題
(最重要的地方)更改Source變成Deploy from a branch，並且把Branch改成如下圖這邊的邏輯是:
1. 從 master (或 main) 分支的 Hugo 原始碼建置 (hugo --minify)
2. 將建置結果 (./demo/public/) 部署到 gh-pages 分支
3. GitHub Pages再從gh-pages branch提供網站
之後Source就不需要再改回GitHub Actions了
如果之後要跟新文章，就直接像一般的git push那樣固定的add->commit->push這樣的流程就可以了，GitHub Actions會自己把東西deploy到public pages