Pagefind 怎麼排除不該搜尋的內容？data-pagefind-ignore 與 exclude_selectors
Pagefind 預設會從頁面 body 建立搜尋內容，但網站導覽、分享工具、重複標題、推薦文章與輔助文字未必適合出現在搜尋結果。要排除它們，先分清楚三種邊界：data-pagefind-body 定義「哪些內容可以被索引」，data-pagefind-ignore 排除索引區域內的一個元素，exclude_selectors 則在 CLI 建置階段套用全站 CSS selector 規則。
直接答案是：先用 data-pagefind-body 圍住文章主體，再用 data-pagefind-ignore 排除局部元件；只有當規則是模板或全站共用政策時，才放進 pagefind.yml 的 exclude_selectors。每次調整都要重跑 production build，並用實際搜尋詞確認沒有誤刪整頁。
先用 data-pagefind-body 定義索引根
data-pagefind-body 是 allowlist 邊界，不是「在頁面上加一個提示」。一旦 Pagefind 在網站中看到這個標記，未標記的頁面可能不再符合索引條件；因此所有應該可搜尋的 layout 都要一致處理。
最小 HTML 結構可以是：
<body> <header>網站導覽</header>
<main data-pagefind-body> <article> <h1>Pagefind 搜尋索引</h1> <p>這段文章內容應該可以被搜尋。</p> </article> </main></body>內建的 nav、footer、script 等結構會被 Pagefind 跳過，但自訂 sidebar、CTA、標籤列或推薦模組不一定符合你的搜尋意圖。放置 body marker 前，先列出首頁、文章、tag、archive 與其他 layout；不要只改一種文章模板，最後讓首頁反而從索引消失。
ZeroOne 目前的 Markdown 元件以 data-pagefind-body 包住文章內容，文章頁標題另用 Pagefind 的 weight 與 metadata 標記。要調整自己的模板，可先查實際產出的 Astro 元件：
rg -n 'data-pagefind-body|data-pagefind-ignore|data-pagefind-weight|data-pagefind-meta' \ src astro.config.mjsdata-pagefind-ignore 適合排除局部內容
當一個區塊位於已索引的 body 裡，使用 data-pagefind-ignore 排除它與子元素的正文：
<main data-pagefind-body> <article> <h1>文章主體</h1> <p>這段文字會進入索引。</p> </article>
<aside data-pagefind-ignore> <h2>推薦文章</h2> <p>這段文案不應影響正文搜尋。</p> </aside></main>預設的 data-pagefind-ignore 會排除元素及其子內容的索引文字，但 Pagefind 仍可能處理其中的 filter、metadata、預設 title 或圖片資訊。若整個區塊連 Pagefind 的其他處理都不應該發生，才使用：
<aside data-pagefind-ignore="all"> <h2>這個區塊不提供任何 Pagefind metadata</h2></aside>all 不是更安全的預設值。它可能同時移除你原本想保留的 metadata 或 filter；先從一般 ignore 開始，再用 build 後的索引結果確認是否需要提高排除層級。
data-pagefind-ignore 和 exclude_selectors 怎麼選
這兩者都能減少噪音，但維護位置不同：
| 情境 | 建議工具 | 原因 |
|---|---|---|
| 某個元件自己知道哪段內容不該被搜尋 | data-pagefind-ignore | 決策和元件 markup 放在一起，重構時較容易一起更新 |
所有頁面的 .site-chrome 都不應進索引 | exclude_selectors | 把規則集中在 Pagefind build 設定，不必重複改每個模板 |
| 只有文章主體可搜尋 | data-pagefind-body | 直接建立索引 allowlist，避免把 layout 雜訊納入 |
| 只想排除整頁的一種檔案或路徑 | CLI 的 site／glob 設定 | 這是頁面發現問題，不是局部 HTML 排除問題 |
pagefind.yml 可以集中放全站規則：
exclude_selectors: - '.site-chrome' - '.recommendation-panel' - '[data-no-search]'Pagefind 的 selector 會影響匹配元素及其子元素。若規則只屬於一個元件，優先使用 attribute；若是所有頁面都一致的 build policy，才用 exclude_selectors。兩層並用沒有問題，但要在 code review 中說清楚哪一層擁有排除規則。
先檢查 metadata 是否被一起排除
搜尋正文和搜尋結果 metadata 是兩個不同問題。data-pagefind-ignore 的預設行為可能仍讓 Pagefind 處理區塊中的部分 metadata，而 data-pagefind-ignore="all" 則連這些資訊都排除。當你用標題、圖片或自訂 data attribute 製作結果卡片時，不能只用「搜尋不到該段文字」判斷設定正確。
可以準備三種測試詞：
- 只出現在文章主體的詞，確認它仍能找到目標頁。
- 只出現在 sidebar 或 CTA 的詞，確認它不會把目標頁推成不相關結果。
- 只出現在被排除區塊標題或 metadata 的詞，確認
index和all的差異符合預期。
如果是多語言網站，也要分別從繁體中文與英文路徑測試；語言欄位、Pagefind index 與結果頁路徑不能只靠同一個語言的結果推論。相關的 Astro 版本升級也可參考 Astro 7 升級與建置清單 中的 Pagefind 輸出檢查。
用 Astro build 驗證索引邊界
先確認專案的建置順序，再執行完整流程。ZeroOne 使用 Astro build 後建立 Pagefind index：
pnpm buildfind dist -maxdepth 3 -type f | sort | rg 'pagefind|index\.html|posts'不要直接編輯 dist 來修正搜尋結果。這裡的目的只是確認：
- 應搜尋的 layout 都產生
data-pagefind-body或等效內容。 - 不應搜尋的導覽、推薦與工具區塊仍在 HTML，但不會污染正文索引。
- Pagefind assets 與 index 在 production build 中產生，且路徑沒有因 adapter 或 base 設定改變。
若一加上 body marker 就有頁面消失，先回到所有 page layout 補齊索引邊界；若只有特定元件污染結果，再將 selector 縮小到該元件，避免把整個 main 或文章頁一起排除。
常見的排除錯誤
- 把
data-pagefind-ignore放在<body>，結果整個網站內容都被排除。 - 只在一種文章模板加
data-pagefind-body，首頁或其他 layout 因未標記而不再索引。 - 用
data-pagefind-ignore="all"排除 CTA，卻同時移除了結果卡片需要的 metadata。 - 以
exclude_selectors排除太寬的父層 selector，連文章正文一起移除。 - 只看瀏覽器畫面，不檢查 build 後的 Pagefind index，誤以為「元素仍在 HTML」就代表它能被搜尋。
排除規則的完成條件不是頁面看起來沒變，而是搜尋結果同時保留正確正文、移除預期噪音，並且沒有讓其他 layout 悄悄退出索引。
常見問題
Q: data-pagefind-ignore 會讓整個頁面從搜尋消失嗎？
A: 不會。它只排除被標記的元素及子元素；要控制整頁是否可搜尋，應處理 data-pagefind-body 的頁面邊界或 Pagefind 的頁面發現設定。
Q: 為什麼加了 data-pagefind-body 後，另一個頁面不見了？
A: body marker 會把索引邊界變成全站需要一致遵守的規則。檢查消失頁面使用的 layout，為應該可搜尋的區域補上 marker，再重新執行 production build。
Q: 什麼時候該用 exclude_selectors？
A: 當排除規則是全站共用的 CSS selector 政策，而不是某個元件的內容決策時使用。若規則只屬於單一元件，把 data-pagefind-ignore 放在 markup 中通常更容易維護。
參考資料：
回報錯字、失效連結，或告訴我你想看的延伸主題。