用Hugo建置靜態網頁

環境設定

#

我的環境是Windows 11，安裝scoopy做套件管理，之後再安裝hugo，讓它獨立在主系統之外，避掉討厭的PATH設定。 例外確保你有安裝git

1. 用powershell裝在D槽, 輸入下面指令

$env:SCOOP='D:\work\Tools\Scoop'
[Environment]::SetEnvironmentVariable('SCOOP', $env:SCOOP, 'User')

1. 解除執行Script的限制

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

1. 安裝scoop

irm get.scoop.sh | iex

1. 安裝hugo 安裝hugo-extended才有漂亮的theme可以用

scoop install hugo-extended

Github Repository

#

先在github建立一個主網頁，名稱和你的帳號同名，若你的帳號為ACCOUNT，你的repository就為ACCOUNT.github.io
之後可以再新增其他的repository給不同的blog，比如 ACCOUNT.github.io/BLOG1
那麼該網頁的網址為https://ACCOUNT.github.io/BLOG1

Configuration

#

設定 Theme

#

選定一個theme, 我自己是使用blowfish。初始化git後下載blowfish:

git init
git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish

將theme/blowfish/config/下的內容複製到root，方便作客製化，避免直接修改theme下的config。config/_default/hugo.toml裡面做以下修改:

theme = "blowfish"
# 你的網頁位置
baseURL = "https://ACCOUNT.github.io/Blog1"
# 修改語言後，你的menu也需要有一份meun.zh-tw.toml
defaultContentLanguage = "zh-tw"
hasCJKLanguage = true
title = "Your Title"

設定 menu

#

[[main]]
identifier="notes"
name="Notes"
url="/categories/"
weight=1

其中的url可以用taxonomies或是指定content/下的某個folder，以上例而言，是直接找categories，也就是你的md檔front matter裡面指定categories，就會在點選Notes這個menu後看到你的category。若你指定的是content下的資料夾，點入就會顯示該資料夾下所有的md檔

設定 Table of Content

#

在config/_default/params.toml將下面設定打開

highlightCurrentMenuArea = true
smartTOC = true
smartTOCHideUnfocusedChildren = true

並且在[article]之下加入

layout = 'main'
showTableOfContents = true

config/_default/markup.toml加入下面設定

[tableOfContents]
  startLevel = 1
  endLevel = 6
  ordered = false

顯示 tags

#

在hugo.toml設定taxonomies

[taxonomies]
  tag = "tags"
  category = "categories"
  series = "series"

在params.toml打開showTaxonomies

showTaxonomies=true

文章中的front matter設定

+++
...
tags=['YourTag']
+++

發布

#

開發時的commit上在master，另開一個獨立的branch - public專門發布網頁，但我不想手動互切branch，改作一個workflow讓github幫我完成: 當我決定發布時，在github上手動觸發網頁更新，若public不存在會自動新增。

name: Deploy Hugo site to GitHub Pages
on:
  workflow_dispatch: # 手動

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4  # 步驟 1: 把你的程式碼抓下來
        with:
          submodules: true         # 確保抓到 Blowfish 主題
          fetch-depth: 0

      - name: Setup Hugo           # 步驟 2: 安裝 Hugo 軟體
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: 'latest'
          extended: true

      - name: Build                # 步驟 3: 執行編譯 (將 md 轉為 html)
        run: hugo --minify

      - name: Deploy               # 步驟 4: 把編譯好的結果推送到 public 分支
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }} # 這是自動生成, 每次執行都不同
          publish_dir: ./public
          publish_branch: public  

更新 commit

#

git add .
git commit
git push

將workflow更新到github

權限設定

#

到github repository的頁面，Setting -> Action -> General -> Workflow permission，選擇Read and write permissions，然後按Save。因為發布網頁需要推送到public branch，必須要有"write"的權限，否則會報錯

執行 workflow

#

點選Action，在左側找到你的workflow “Deploy Hugo site to GitHub Pages”，按Run workflow，會需要一點時間，完成後等個一分鐘你的網頁就上線了。(網頁在config/default/hugo.toml裡的baseURL)

切換到public branch

#

點選Settings，在左側找到Pages，在"Build and Deployment"裡面找到branch，選擇Public後Save