內容目錄連結是 toc_1，正文卻沒有可以跳的目標

整理日期：2026-08-10

狀況

一篇知識庫文章的內容目錄看起來正常，連結也依序產生了：

<a href="#toc_1">第一個章節</a>
<a href="#toc_2">第二個章節</a>

點擊後，網址會出現 #toc_1，頁面卻沒有移動到第一個標題。

這種狀況很容易先懷疑平滑捲動、固定頁首或 offset。但檢查正文 DOM 後，頁面裡根本沒有 id="toc_1"。

網站原本為了把目錄放在自訂文章版型的指定位置，另外做了一層目錄 wrapper。這層程式可以叫出 Easy Table of Contents 的目錄清單，但正文仍由原本的文章模板輸出。

後來又加上一段 filter。只要外掛產生的 anchor 含有 %，就把它改成 toc_1、toc_2 這類流水號，想讓中文標題的網址短一點。

兩段程式各自都能執行，合在一起卻少了一半：

瀏覽器不是不會捲動，而是找不到要捲到哪裡。

只看網址後面有沒有 #ID 不夠。有效的錨點至少要同時具備：

href="#同一個值"  →  頁面內剛好有一個 id="同一個值"

Easy TOC 原本會掃描文章的 H1 到 H6，產生目錄連結，再把相同 anchor 寫進正文標題附近的 <span>。

中文標題產生的 fragment 看起來可能是一長串百分比編碼，但那不是錯誤。只要目錄的 href 和正文的 id 相同，瀏覽器就能正常跳轉。

現有程式用 strpos($return, '%') 判斷中文也不可靠。Emoji、全形標點、其他非 ASCII 語言與部分特殊字元，網址編碼後同樣會出現 %。

toc_1 不是備援機制。它只是另一套命名方式，而且章節重排後，原本的 toc_1 可能改指完全不同的內容。

這次的根本原因是：目錄與正文沒有使用同一次 Easy TOC 處理結果。

優先使用外掛原生流程：

沒有手動 ID 時，filter 應直接保留外掛原本產生的 $return：

add_filter('eztoc_url_anchor_target', function ($return, $heading) {
    return $return;
}, 10, 2);

如果版面限制讓自訂 wrapper 一定要保留，就不能只取得目錄 HTML。wrapper 必須同時輸出同一次 heading extraction 處理後的正文，讓目錄與正文共用同一份 anchor mapping。

這條路需要維護更多程式與快取失效邏輯，只有原生自動插入無法滿足版面時才值得做。

標題如果已經是：

<h2 id="manual-anchor">章節標題</h2>

又讓外掛在裡面加入同名 <span id="manual-anchor">，同一頁就會出現兩個相同 ID。

要保留手動 ID，可以讓 H 標籤本身成為唯一目標，或把 ID 交給外掛產生的 span。不要兩邊都留。