Hugo Mainroad Theme設定

Shan

星期六, 三月 22, 2025

Misc

Translations: EN, ZH

Hugo是一套用Go寫的site generator，它的優勢是能有效率的建立網站，能夠處理模版產生的文字/靜態網頁內容，有點像是JS/React的Gatsby，或是Jekyll

官網有quick start，跟著做可以很快產生靜態網站，步驟大致分為3組：

準備
設定hugo專案
發布新文章

準備

確認環境有安裝hugo和git

# 在mac環境用brew安裝
brew install hugo
# 檢查hugo版本
hugo version

# mac最方便的方法是安裝 Xcode Command Line Tools
# 安裝好之後一樣檢查版本，確定有成功
git --version

設定hugo專案

# 建立一個叫做的專案
hugo new site quickstart
cd quickstart
git init

# 選定要用的theme
# git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
# echo "theme = 'ananke'" >> hugo.toml
# hugo server

自選一個叫做mainroad的theme替代ananke

# 選定要用的theme
git clone https://github.com/vimux/mainroad.git themes/mainroad
git submodule add https://github.com/vimux/mainroad.git themes/mainroad
echo "theme = 'mainroad'" >> hugo.toml # 到hugo.toml確定有沒有寫進去
hugo server

依照mainroad theme的範例，設定hugo.toml

使用自訂theme要注意的是，有時候更新還沒有跟上最新的hugo，例如這次在設定過程遇到的是author取用方式已經從 .Site.Author.name 改成.Site.Params.author.avatar，因此改成較新的寫法，在hugo.toml 把最外層的 [Author] 搬到 [Params]裡面

# 修改前
[Author]
  name = "name"
  bio = "bio"
  avatar = "img/avatar.png"

# 修改後
[Params]
	# ...其它設定
	[Params.author]
	    name = "name"
	    bio = "bio"
	    avatar = "img/avatar.png"

在mainraod theme的github pull requests，其實有author相關的修正，但還沒有被merge進去 https://github.com/Vimux/Mainroad/pulls

改好之後看能不能順利跑起來

hugo server

增加第一篇新文章

# 先停掉server: Ctrl + C
hugo new content content/posts/my-first-post.md

編輯內容後，重啟server

# 包括draft
hugo server -D

Theme

theme是事先寫好的樣式模版，重要的元件有layouts、static、archetypes和data資料夾

layouts: HTML template
static: css, JavaScript, images, etc
archtypes: hugo new command 需要用來建立新文章的檔案
data: 支援theme的相關的檔案

Static files

如果是static檔案，像是author avatar，加到themes/{themName}/static/img/資料夾下，覆蓋原本的avatar.png

Multilingual

多國語言設定需要調整hugo設定檔 (hugo.toml)、以及會用到設定檔參數的 layout、檔案架構、等

defaultContentLanguage = "en"

[languages]
  [languages.en]
    languageName = "English"
    languageCode = "en"
    contentDir = "content/en"  # English content folder
    weight = 1  # Lower weight = higher priority (default language)
    
  [languages.zh]
    languageName = "中文 (繁體)"  # Traditional Chinese
    languageCode = "zh-Hant"      # Standard code for Traditional Chinese
    contentDir = "content/zh-hant"
    weight = 2

每設定到一個段落都用hugo server 看一下在開發環境是否正常顯示:

http://localhost:1313/
http://localhost:1313/zh/

Authorbox和中英文顯示沒有問題，但這時發現mainroad原本的sidebar 壞掉了，在首頁時sidebar在右邊，但在post list頁面sidebar卻跑到左邊

[Params.sidebar]
  home = "right"
  # 把sidebar list從左邊改成右邊
  list = "right"

另外就是section navigation不見了，是因為現在區分成不同語言，需要設定 menu.main

[languages]
  [languages.en]
    languageName = "English"
    languageCode = "en"
    contentDir = "content/en"  # English content folder
    weight = 1  # Lower weight = higher priority (default language)
    [[languages.en.menu.main]]
      name = "Posts"
      url = "/posts/"
      weight = 10

  [languages.zh]
    languageName = "中文 (繁體)"  # Traditional Chinese
    languageCode = "zh-Hant"      # Standard code for Traditional Chinese
    contentDir = "content/zh-hant"
    weight = 2
    [[languages.zh.menu.main]]
      name = "文章"
      url = "/zh/posts/"
      weight = 10

都符合預期再用hugo或hugo --gc(清除沒在用的檔案) build更新 public資料夾，並發布到production

發布網站

# 先build
hugo

Host and deploy https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/

建一個GitHub repo

git remote add origin https://github.com/<your-gh-username>/<repository-name>
git branch -M main
git push -u origin main

Deploy with Cloudflare Pages

常用的hugo指令

# build and generate static stie for hosting
hugo

# also removes unused files automatically
hugo --gc

# run on development server
hugo server

# run on development server with drafts
hugo server -D

# provide the -b or --baseURL flags with the CF_PAGES_URL environment variable to hugo build command
hugo -b $CF_PAGES_URL

準備