靜態站搜尋必須在 build 時或 client runtime 完成。選擇整包序列化 + client 載入這條路時，核心設計軸是：

Fuse.js 與 MiniSearch 是這條路上的兩個主要實作。差異在匹配策略（fuzzy vs 全文），共享的是「一包索引載入瀏覽器、之後所有查詢不再出站」這個骨幹。

核心設計：build 時序列化 + runtime in-memory

商業邏輯：把搜尋放在 client runtime 的關鍵是搜尋不再跨網路來回。第一次載入索引之後，每次打字的匹配都在使用者的 RAM 內完成，不受網路延遲影響、不受後端服務狀態影響、甚至不需要網路連線。

此設計把「索引存放」從伺服端或 CDN 移到了訪客自己的瀏覽器，換得 runtime 的完全獨立。

CASE：整個流程兩個時點：

Build time（Hugo 階段）：Hugo 用 custom output format 產出一份 JSON，每筆一個頁面。

1{ "title": "WAF", "url": "/backend/knowledge-cards/waf/",
2  "description": "說明 WAF 如何在入口層過濾攻擊",
3  "content": "完整內文…" }

Runtime（瀏覽器階段）：使用者打開搜尋頁，browser fetch JSON → library 在 memory 中建索引 → 使用者打字 → library 匹配 → 結果渲染。

第一次 fetch + build index 通常 100-500ms；之後的每次查詢在 memory 內匹配，一般 <10ms。

架構選擇：作者定義索引內容

商業邏輯：索引的範圍與欄位由誰決定，這件事決定了搜尋結果的邊界。Fuse.js / MiniSearch 採「作者顯式宣告」的路線 — Hugo template 明確列出哪些 section 進索引、每筆要哪些欄位。

這個選擇讓搜尋結果成為作者設計決策的產物：想排除 work-log 類別就不列入 range；想讓 tag 也可搜就加一個 tags 欄位到 JSON；想降低索引大小就只存 title + description 而不存 content。

CASE：layouts/index.json 決定 JSON 內容：

 1{{- $pages := where .Site.RegularPages "Section" "in" (slice "posts" "backend" "go" "python") -}}
 2[
 3{{- range $i, $p := $pages -}}
 4  {{- if $i }},{{ end }}
 5  { "title": {{ .Title | jsonify }},
 6    "url": {{ .RelPermalink | jsonify }},
 7    "description": {{ .Description | jsonify }},
 8    "content": {{ .Plain | jsonify }} }
 9{{- end -}}
10]

配套在 hugo.toml：

1[outputs]
2  home = ["HTML", "RSS", "JSON"]
3
4[outputFormats.JSON]
5  mediaType = "application/json"
6  baseName = "index"
7  isPlainText = true

Build 後 public/index.json 就是整站可搜內容的權威來源。

整合步驟（以 Fuse.js 為例）

1. Hugo 產生 index.json

核心動作：設定 custom output format，寫 template 輸出 JSON。

見上方「架構選擇」段落的 hugo.toml 與 layouts/index.json。

2. 搜尋頁載入 library + index

核心動作：前端一個 <input>、一段 script，完成 fetch + 建索引 + 匹配 + 渲染。

 1{{ define "main" }}
 2<input id="q" placeholder="搜尋…">
 3<ul id="results"></ul>
 4
 5<script src="https://cdn.jsdelivr.net/npm/fuse.js@7/dist/fuse.min.js"></script>
 6<script>
 7  fetch('{{ "index.json" | relURL }}')
 8    .then(r => r.json())
 9    .then(data => {
10      const fuse = new Fuse(data, {
11        keys: ['title', 'description', 'content'],
12        threshold: 0.3,
13        includeMatches: true
14      });
15      document.getElementById('q').addEventListener('input', e => {
16        const results = fuse.search(e.target.value).slice(0, 20);
17        document.getElementById('results').innerHTML = results
18          .map(r => `<li><a href="${r.item.url}">${r.item.title}</a>
19                     <p>${r.item.description}</p></li>`)
20          .join('');
21      });
22    });
23</script>
24{{ end }}

30 行內可以跑起來。

3. MiniSearch 的 API 差異

核心動作：選 MiniSearch 時，API 形狀相近、配置項不同。

 1const mini = new MiniSearch({
 2  fields: ['title', 'description', 'content'],
 3  storeFields: ['title', 'url', 'description'],
 4  searchOptions: {
 5    boost: { title: 3, description: 2 },
 6    prefix: true,
 7    fuzzy: 0.2
 8  }
 9});
10mini.addAll(data);
11const results = mini.search(query);

• boost 決定各欄位命中的權重：title 命中比 content 命中重 3 倍
• prefix: true 讓 “WA” 命中 “WAF”
• fuzzy: 0.2 開啟 approximate match，容錯程度可調

方案的內在屬性

與 runtime 獨立相關的延伸特徵：

• 離線可用：索引載入後所有查詢不需要網路；PWA 加 Cache API 讓索引也能離線快取
• 自託管：索引資料不離開你的網域；敏感內容或私有文件特別適合
• 隱私：訪客查詢字串不會送到任何第三方服務

與 UI 獨立相關的延伸特徵：

• 樣式與互動 100% 可控：搜尋框位置、結果卡排版、modal 與否、鍵盤操作 — 每一項都由作者決定
• 與 theme 緊密整合：UI 可以直接套用站上其他元件的 CSS variable 與設計 token

兩家 library 的定位差異

Fuse.js 與 MiniSearch 共享核心架構，設計重心不同：

兩者的 API 形狀相近，切換成本低。決定用哪一個，主要看希望怎麼對待 query：可能有錯字的模糊輸入偏向 Fuse.js，結構化的技術關鍵字偏向 MiniSearch。

運作特徵

Index 在首次載入

核心定義：索引是一份 JSON，使用者打開搜尋頁時由瀏覽器一次性 fetch。

含義：首次延遲 = 下載 JSON + library 建索引。常見做法是在 DOMContentLoaded 就 preload JSON，讓使用者看到搜尋框時索引已建好、第一次打字即可查詢。

規模適合度：幾百到一兩千頁、索引 JSON 幾百 KB 到 1-2MB 的站，體驗最穩定。索引大小由作者在 Hugo template 內決定 — 只索引 title + description 可以把 size 壓到很小。

索引範圍由作者決定

核心定義：Hugo template 明確列出要進索引的 section 與欄位。

含義：搜尋結果的邊界是作者設計決策。增減 section、增減 field、調整儲存策略，都在 template 這一層直接生效。

Tokenization 依 library 而異

核心定義：Fuse.js 採 character-level 匹配；MiniSearch 預設用空白分詞。

含義：

• Fuse.js 對中文天然能搜，不需要斷詞設定
• MiniSearch 對中文需要傳自訂 tokenize function，可以一個字一 token，或接 Intl.Segmenter 做詞界切分

UI 由作者自己寫

核心定義：library 只提供搜尋 API，不提供視覺組件。

含義：排版、鍵盤操作、focus management、ARIA 這些 UI 層責任由作者顯式實作。收穫是與 theme 完全融合的客製體驗。

適合的場景

• 站的規模穩定在幾百到一兩千頁
• UI 需要深度客製、與 theme 風格緊密整合
• 想要最單純的 build pipeline（無 post-build step、無額外工具）
• 內容敏感、希望索引不離開自家網域
• 希望搜尋在離線狀態仍可用
• 需要 fuzzy match（Fuse.js）或精細 field boost + prefix（MiniSearch）

靜態站沒有後端可以接查詢，所有搜尋工作必須在兩個時點之一完成：build 時產生索引、client runtime 執行匹配。這個前提決定了所有靜態站搜尋方案共同面對的兩個設計軸：

方案差異來自這兩軸的組合。Pagefind 選的是「build 時產生、按需載入」，它的所有設計決策都是這個選擇的延伸。

核心設計：索引切片與按需載入

商業邏輯：搜尋索引的 scaling 關鍵是單次查詢需要下載多少資料，而非壓縮率或演算法效率。若索引是一整包、每次查詢都要先整包載入，訪客體驗與站的大小線性綁定 — 站大 10 倍，首次搜尋延遲 10 倍。

要脫離這條綁定，索引必須能以「與查詢相關」的粒度切片、按需傳輸。這把「索引多大」的問題從訪客手上移回 build pipeline。

CASE：Pagefind 的索引是三層結構：

查「WAF」時，client 下載路徑是：entry（10KB）→ 涵蓋 “W” 的 index chunk（~30KB）→ 命中文章的 fragment（每筆 3KB）。總傳輸量與全站大小幾乎脫鉤 — 站擴大 10 倍，單次搜尋仍然只下載「W」那個 chunk 與少數 fragment。

架構選擇：爬 rendered HTML

商業邏輯：索引內容的來源有兩種可能：source 層（markdown、frontmatter、結構化資料）或 output 層（render 後的 HTML）。選哪一層決定工具與 framework 的耦合程度 — source 層要求工具懂特定 framework 的內容模型；output 層只要求結果是 HTML。

Pagefind 選 output 層。含義是：它跟 Hugo、Jekyll、Zola、Next.js static export 完全解耦，只要該 framework 產出的是 HTML，Pagefind 都能索引。

CASE：此選擇在 blog 端的具體要求：希望被搜到的內容必須出現在 rendered HTML 上。frontmatter 的 description 欄位若只存在於 markdown source、沒被 theme 輸出成 <meta> 或可見文字，就不會進索引。

這個 blog 天然滿足 — theme 把 description 寫進 <meta name="description">，render hook 也用它做 tooltip。移植到任何其他 static site generator，只要目標的 output HTML 有這些欄位，搜尋整合不用重寫。

整合步驟

1. Build pipeline

核心動作：Hugo build 後加一步 Pagefind。

1hugo --minify
2npx -y pagefind --site public

兩步，沒有中間檔。Pagefind 自行讀取 public/ 的 HTML，將索引寫回 public/pagefind/。

2. 搜尋頁路由

核心動作：建立 Hugo 單頁，指向專屬 layout。

1---
2title: "搜尋"
3layout: search
4sitemap:
5  disable: true
6---

sitemap.disable 避免搜尋頁自己被 Hugo sitemap 收錄。

3. UI 掛載

核心動作：在 layout 中載入 Pagefind UI 資源，指定 mount point。

 1{{ define "main" }}
 2<div data-pagefind-ignore>
 3  <link href="{{ "pagefind/pagefind-ui.css" | relURL }}" rel="stylesheet">
 4  <div id="search"></div>
 5  <script src="{{ "pagefind/pagefind-ui.js" | relURL }}"></script>
 6  <script>
 7    window.addEventListener('DOMContentLoaded', function () {
 8      new PagefindUI({
 9        element: "#search",
10        showSubResults: true,
11        translations: { placeholder: "搜尋卡片或文章…" }
12      });
13    });
14  </script>
15</div>
16{{ end }}

兩個細節：

• data-pagefind-ignore 告訴 Pagefind 這頁本身不要進索引（避免搜「搜尋」出現搜尋頁）。
• relURL 處理 baseURL 的 subpath（例如 /blog/），讓 UI 自動推斷 chunk 相對位置。

4. CI workflow

核心動作：GitHub Actions 在 Hugo build 步驟後插入 Pagefind。

1- name: Build Pagefind search index
2  run: npx -y pagefind --site public

ubuntu-latest runner 內建 node，npx -y 首次執行會下載並 cache binary，後續執行直接從 cache 取用。

方案的內在屬性

評估 Pagefind 不看「比較快」「比較省事」這類時間維度，用下列內在屬性：

內建的一等公民特性：

• Filter by facet：data-pagefind-filter="type:card" 標在 HTML 元素上，UI 自動出現對應 filter checkbox
• Snippet highlighting：命中的關鍵字在結果摘要中高亮
• 無障礙：Component UI（1.5.0+）內建 keyboard navigation、ARIA label、screen reader 公告

這些特徵都源自「build 時產生 + 按需載入」這個核心選擇的延伸，不是外掛功能。

運作特徵

zh-tw 走 character n-gram

核心定義：Pagefind 對非空白分詞語言採 n-gram — 以字元序列作為匹配單位，而非詞。

行為：搜「負載平衡」能命中「負載平衡器」、「負載平衡器測試」等任何包含該字元序列的頁面。啟動時會印一行 stemming note，那是針對屈折變化語言（英文、德文）的 stemming 提示，對中文無意義也無限制。

邊界：少數情境下跨詞邊界的字元組合會誤命中（例如搜「負載過」可能命中「負載過高」與「負載過往」）。在名詞為主的技術站影響極小。

索引來自 rendered HTML

核心定義：索引內容 = Pagefind 在 public/*.html 看到的可見文字與 meta tag。

含義：想加入索引的欄位必須出現在 output HTML 上。想排除的區塊用 data-pagefind-ignore 標記。想作為 filter 的屬性用 data-pagefind-filter="name:value"。

Default UI 的樣式是 Pagefind 自家風格

核心定義：PagefindUI component 有固定的視覺設計，透過 CSS variable 可微調顏色、圓角、spacing。

含義：想要與 theme 完全融合有兩條路 — 覆寫 CSS variable（官方 docs 列出可覆寫清單），或改用 Pagefind JS API 自己組 UI（更完整客製）。

Build pipeline 多一步

核心定義：Pagefind 是 Hugo build 外的獨立步驟。

含義：CI 與本地都要記得跑 npx pagefind。這個 blog 以 Makefile 的 make site 封裝 hugo + pagefind 兩步，把「記得」轉成 infrastructure 強制項。

適合的場景

• 靜態站、內容持續成長
• 部署在 GH Pages / Netlify / Cloudflare Pages 等純靜態平台
• 希望零外部依賴、完全自託管
• 內容以文字為主（blog、docs、knowledge base）
• 未來可能換 framework — 希望搜尋整合不隨之重寫