Hugo + Bear Cub 主題設定完整教學

2025-08-22

Hugo + 主題設定完整教學

這篇文章記錄了我從零開始建立 Hugo 部落格並安裝 Bear Cub 主題的完整過程，包含常見的設定問題和解決方案。

為什麼選擇 Hugo ？

特點：Go 語言寫的，速度極快

優點

生成速度最快（

單一 binary → 不需要安裝 Node/Ruby 環境，跨平台好用

主題多

部署方便（build → 靜態檔 → push）

缺點

需要本地 build，再 push 結果到 GitHub Pages（不像 Jekyll 原生）

模板語法（Go Template）對新手稍有難度

Plugin 擴展性不如 Node.js 生態

基本安裝與設定

1. 初始化 Hugo 專案

1# 在現有的 GitHub 專案中初始化 Hugo
2hugo new site . --force

2. 安裝 Bear Cub 主題

1# 使用 git submodule 安裝（推薦）
2git submodule add https://github.com/clente/hugo-bearcub.git themes/hugo-bearcub

3. 基本設定檔案 (hugo.toml)

 1# 基本設定
 2baseURL = 'https://你的用戶名.github.io/blog'
 3theme = 'hugo-bearcub'
 4copyright = '你的名字 (CC BY 4.0)'
 5defaultContentLanguage = 'zh-tw'
 6
 7# 產生 robots.txt 以利於 SEO
 8enableRobotsTXT = true
 9
10# 設定語法高亮
11[markup]
12  [markup.highlight]
13    lineNos = true
14    lineNumbersInTable = false
15    noClasses = false
16  [markup.goldmark]
17    [markup.goldmark.renderer]
18      unsafe = true
19
20# 多語言模式設定
21[languages]
22  [languages.zh-tw]
23    title = '我的部落格'
24    languageName = 'zh-TW 🇹🇼'
25    LanguageCode = 'zh-TW'
26    contentDir = 'content'
27    [languages.zh-tw.params]
28      madeWith = '使用 [Bear Cub](https://github.com/clente/hugo-bearcub) 製作'
29
30[params]
31  # 網站描述
32  description = '我的個人部落格，分享技術與生活'
33  
34  # 網站標題
35  title = '我的部落格'
36  
37  # 日期格式
38  dateFormat = '2006-01-02'
39  
40  # 主題樣式 (original 或 herman)
41  themeStyle = 'original'
42  
43  # 自動產生社群媒體卡片
44  generateSocialCard = true
45  
46  # 作者資訊
47  [params.author]
48    name = '你的名字'
49    email = 'your.email@example.com'

首頁內容自訂

建立首頁內容檔案

在 content/_index.md 建立檔案：

 1---
 2title: "首頁"
 3---
 4
 5# 歡迎來到我的個人部落格
 6
 7嗨！我是 **你的名字**，歡迎來到我的數位天地。
 8
 9## 關於這個部落格
10
11這裡是我分享想法、學習心得和生活點滴的地方。你可以在這裡找到：
12
13- **技術文章**：程式開發經驗分享
14- **學習筆記**：新技術的學習過程
15- **專案記錄**：有趣的專案開發歷程
16- **生活感悟**：日常生活的思考與體驗
17
18## 最新文章
19
20歡迎查看我的[最新文章](/posts/)，或者透過[標籤](/tags/)來瀏覽特定主題的內容。
21
22## 聯絡我
23
24如果你想要與我交流或合作，歡迎透過以下方式聯絡：
25
26- Email: your.email@example.com
27- 有任何問題或建議，也歡迎在文章下方留言
28
29---
30
31*感謝你的造訪，希望這些內容對你有所幫助！*

建立文章

快速建立新文章

1# 建立新文章
2hugo new content posts/文章標題.md

文章格式範例

 1---
 2title: "文章標題"
 3date: 2025-08-22T20:41:50+08:00
 4draft: false
 5description: "文章描述，用於 SEO 和社群分享"
 6tags: ["標籤1", "標籤2"]
 7---
 8
 9文章內容寫在這裡...
10
11## 小節標題
12
13- 列表項目
14- 另一個項目
15
16### 程式碼範例
17\`\`\`bash
18echo "Hello Hugo!"
19\`\`\`

文章摘要與繼續閱讀設定

摘要顯示功能

為了避免文章列表頁面顯示完整內容，我們可以設定文章摘要功能，讓列表只顯示文章摘要並提供「繼續閱讀」按鈕。

1. 自動摘要設定

在 hugo.toml 中設定摘要長度：

1# 摘要設定
2summaryLength = 200  # 摘要字數限制

說明

當文章沒有手動設定摘要時，Hugo 會自動截取前 200 個字元
對於中文內容，200 個字元大約是 100-150 個中文字
對於英文內容，200 個字元大約是 30-40 個英文單詞

2. 手動摘要設定

方法一：使用 `` 標記

在文章中插入  來精確控制摘要位置：

 1---
 2title: "文章標題"
 3date: 2025-01-XX
 4tags: ["標籤1", "標籤2"]
 5---
 6
 7這是文章的開頭部分，會顯示在列表中。
 8
 9這裡是更多內容...
10
11<!--more-->
12
13這裡是文章的其餘部分，只會在單篇文章頁面中顯示。

方法二：使用 `description` 參數

在文章的 front matter 中設定 description：

1---
2title: "文章標題"
3date: 2025-01-XX
4description: "這是文章的摘要，會顯示在列表中"
5tags: ["標籤1", "標籤2"]
6---
7
8文章內容...

3. 摘要優先順序

Hugo 的摘要顯示優先順序：

 標記 - 最高優先級
description 參數 - 第二優先級
自動截取 - 使用 summaryLength 設定

4. 列表頁面樣式

設定完成後，文章列表會以卡片式設計顯示：

文章標題：可點擊進入完整文章
發布日期：顯示在標題旁邊
文章摘要：只顯示摘要內容
繼續閱讀按鈕：當文章被截斷時顯示
標籤：顯示文章相關標籤

GitHub Actions 自動部署

設定工作流程

在 .github/workflows/hugo.yml 建立自動部署設定：

 1name: Deploy Hugo site to GitHub Pages
 2
 3on:
 4  push:
 5    branches: ["main"]
 6  workflow_dispatch:
 7
 8permissions:
 9  contents: read
10  pages: write
11  id-token: write
12
13jobs:
14  deploy:
15    runs-on: ubuntu-latest
16    steps:
17      - uses: actions/checkout@v4
18        with:
19          submodules: recursive
20      
21      - name: Setup Hugo
22        uses: peaceiris/actions-hugo@v2
23        with:
24          hugo-version: 'latest'
25          
26      - name: Build
27        run: hugo --minify
28        
29      - name: Deploy to GitHub Pages
30        uses: peaceiris/actions-gh-pages@v3
31        with:
32          github_token: ${{ secrets.GITHUB_TOKEN }}
33          publish_dir: ./public

常見問題與解決方案

社群媒體預覽卡片顯示亂碼問題

當你在 Discord、Facebook 等社群媒體分享文章時，如果預覽卡片中的中文顯示為問號（？），這是因為預設字型不支援中文字符。

問題表現

分享連結時，預覽卡片的標題顯示為問號
作者名稱顯示為 map[name:作者名稱] 而不是純文字

解決方案

1. 建立客製化的社群媒體卡片檔案

首先，在你的專案根目錄建立目錄並複製檔案：

1# 建立 layouts/partials 目錄
2mkdir -p layouts/partials
3
4# 複製主題的 social_card.html 到你的專案中
5cp themes/hugo-bearcub/layouts/partials/social_card.html layouts/partials/

2. 修改字型設定

編輯 layouts/partials/social_card.html 檔案（注意這是你專案中的檔案，不是主題檔案）：

1<!-- 將第 2 行的字型 URL 替換為支援中文的字型 -->
2{{ $font := resources.GetRemote "https://github.com/adobe-fonts/source-han-sans/raw/release/OTF/TraditionalChinese/SourceHanSansTC-Bold.otf" }}

3. 修正作者名稱顯示

在同一個檔案中，找到第 27 行並修改：

1<!-- 原來的程式碼 -->
2{{ $author := (default $.Site.Params.author.name ($.Param "author") ) }}
3
4<!-- 修改為 -->
5{{ $author := (or ($.Param "author") $.Site.Params.author.name) }}

重要說明：我們將檔案複製到專案的 layouts/partials/ 目錄而不是直接修改主題檔案，這樣做的好處是：
保持主題的 git submodule 乾淨
未來更新主題時不會遺失客製化設定
Hugo 會優先使用專案中的檔案覆蓋主題檔案

4. 確保社群媒體卡片功能開啟

在 hugo.toml 中確認設定：

1[params]
2  # 自動產生社群媒體卡片
3  generateSocialCard = true

字型選擇說明

Source Han Sans TC：Adobe 思源黑體繁體中文版本，支援完整中文字符集
替代方案：也可以使用 Google 的 Noto Sans CJK 字型
檔案大小：中文字型檔案較大，但現代瀏覽器會快取字型檔案

修改完成後，重新建立並部署網站，社群媒體預覽就會正確顯示中文內容了。

實用技巧與其他設定

本地開發

1# 啟動開發伺服器
2hugo server
3
4# 包含草稿
5hugo server --buildDrafts
6
7# 指定 IP 和 Port
8hugo server --bind 0.0.0.0 --port 1313

不同電腦上的工作流程

主要開發電腦

安裝 Hugo 進行完整開發
可以本地預覽和測試

其他電腦/緊急更新

只需要 Git 和文字編輯器
直接編輯 Markdown 檔案推送即可
GitHub Actions 會自動編譯和部署

常見檔案位置

設定檔：hugo.toml
首頁內容：content/_index.md
文章：content/posts/
主題：themes/hugo-bearcub/
靜態檔案：static/

總結

透過這個設定流程，我們成功建立了：

快速載入的靜態部落格
支援繁體中文的介面
自動化的 GitHub Pages 部署

現在你可以專注於寫作，讓 Hugo 和 GitHub Actions 處理其他的技術細節！

這篇教學記錄了我的實際設定過程，希望對其他想要建立 Hugo 部落格的朋友有所幫助。

#hugo #bear cub #blog心得