跳转至

使用 Hugo 生成技術文件並推送到 GitPage 服務

介紹

```bash showLineNumbers 作業環境：Windows + WSL 服務管理： 主要應用：Hugo 功能重點： a. 自架 Hugo 技術文章的部落格 b. 開啟全文搜尋功能 c. 打包推送到 GitPage 服務 

## 下載並安裝 Hugo 套件

### 1. 下載官方 .deb（建議）

去 Hugo release
 下載最新 extended 版（一定要 extended，不然 SCSS 會炸）。
例如：

```bash
wget https://github.com/gohugoio/hugo/releases/download/v0.150.0/hugo_extended_0.156.0_Linux-64bit.tar.gz
HTTP request sent, awaiting response... 404 Not Found
2025-09-16 22:38:37 ERROR 404: Not Found.
sudo dpkg -i hugo_extended_0.139.0_linux-amd64.deb
下載 v0.150.0 Extended 版本

前往 Hugo Releases 頁面 ，並下載適用於 Linux 的 Extended 版本。

2. 執行相關指令安裝 Hugo

在你的 WSL 環境中，執行以下命令來安裝 Hugo： 

tar -xzf hugo_extended_0.150.0_Linux-64bit.tar.gz
sudo mv hugo /usr/local/bin/hugo

安裝後檢查： 

hugo version

生成技術文件

1. 寫第一篇文章

hugo new posts/hello-world.md

會在 content/posts/ 底下生出一個 md 檔。 draft: true → 改成 false 才會顯示。

本地預覽 

hugo server -D

2. 先 build Hugo 網站

假設你的 Hugo 專案在 myblog/： 

cd myblog
hugo -D

會在 myblog/public/ 生成靜態檔。

-D 表示 draft 也生成。

將 public/ 推到 GitHub Pages 方法 A：單 repo (username.github.io)

Repo 名稱必須是 username.github.io。

public/ 裡面所有檔案直接推到 main branch。

GitHub Pages 會自動啟用，網址就是 https://username.github.io/。

3. 用 Hugo 產生新頁面（content page）

假設你想新增一篇文章在 posts： 

hugo new posts/my-new-page.md


內容大概是：

---
title: "My New Page"
date: 2025-09-16T22:00:00+08:00
draft: true
---

draft: true → Hugo 不會 build 到 public

想上線就改成 draft: false 或 hugo -D build

GitHub Pages

1. 啟用

打開你的 repo → Settings → Pages

Source 選 branch（main 或 gh-pages）

2. 頁面訪問異常

因為我剛切換路徑（gh-pages branch） 訪問剛發佈的 https://example.org/posts/my-new-page1/ 時候顯示以下錯誤訊息

Example Domain
This domain is for use in illustrative examples in documents. You may use this domain in literature without prior coordination or asking for permission.

More information...
代表你 baseURL 是 https://example.org/

根目錄找一下： 直接拉 theme 的範例可能會不是config.toml 會是其他名稱 我是 hugo.toml

如果真沒有，自己建一個 config.toml 在專案根目錄： 

baseURL = "https://username.github.io/myblog/" # 沒有 /myblog/ 就自己拿掉這個路徑
languageCode = "en-us"
title = "My Blog"
theme = "PaperMod"

3. 部署

  1. Hugo 生成的靜態頁面會放在 /public 路徑下
  2. 這個步驟就是把/public 路徑下全部都拷貝到gitpage 專案底下而已
wsl
/mnt/d/$ cd myblog/
/mnt/d/myblog$ cd content/posts/
/mnt/d/myblog/content/posts$ nano my-new-page1.md
/mnt/d/myblog/content/posts$ cp -a /mnt/d/myblog/public/. /mnt/d/username.github.io/
# . 在最後面很重要，表示把 public/ 裡所有檔案和資料夾都複製到目標資料夾，而不會多一層 public/
# 避免漏掉子資料夾或檔案
/mnt/d/myblog/content/posts$ cd /mnt/d/myblog/
/mnt/d/myblog$ hugo -D

因為我在wsl加ssh所以切過來這推 

/mnt/d/username.github.io$

推到分支更新 GitHub Pages 

git add .
git commit -m "deploy hugo site"
git branch -M gh-pages
git remote add origin git@github.com:username/myblog.git
git push -f origin gh-pages

設置 Hugo 的搜尋功能

1. 搜尋引擎

預設 PaperMod 是用 Lunr.js。

它會去讀 /index.json 來跑全文檢索。

index.json 的生成

你需要在 config.toml 裡啟用 JSON 輸出：

[outputs]
  home = ["HTML", "RSS", "JSON"]
這樣 Hugo build 的時候才會輸出 public/index.json。

本地測試

hugo server -D
http://localhost:1313/index.json 要能打開，看到文章 JSON。

2. PaperMod 搜尋機制

內建支援 Lunr.js 搜尋 但記得要打開 params 裡的 enableSearch

你在 config.toml（或 hugo.toml）裡開啟：

[params]
  enableSearch = true

[params] 是 主題自訂參數。

去讀取 /index.json，然後在前端跑全文檢索。

3. 查看內建的 JS

PaperMod 的搜尋功能不是靠 Hugo 自己魔法出現的，而是靠 主題本身內建的 JS + 模板。

ls themes/PaperMod/assets/js/

新一點的 PaperMod repo 是 fastsearch.js

這版 PaperMod 有搜尋頁 (search layout)，但不是「右上角放大鏡」的 popup 模式，而是 「跳轉到 /search 頁面」 的設計。

也就是說：

fastsearch.js 會在 /search/ 頁面啟動，從 index.json 拉全文索引。

cat themes/PaperMod/layouts/partials/header.html | grep search

header.html 裡的這段： 

$is_search := eq (site.GetPage .KeyName).Layout `search`
<a href="{{ .URL | absLangURL }}" ...>
表示導航列如果配置了一個「Search」menu item，它就會連到 /search。

4. 新增搜尋頁

在 content/search/_index.md 建立搜尋頁：

hugo new search/_index.md
Content "/mnt/d/myblog/content/search/_index.md" created
編輯內容

---
title: "Search"
layout: "search"
---

在 config.toml（或 hugo.toml）加一個 menu 指向 /search：

[[menu.main]]
identifier = "search"
name = "Search"
url = "/search/"
weight = 10

重新 hugo server -D → 你會在導覽列看到「Search」連結，點進去就是全文檢索頁。