問題症狀
以 Hugo+Docsy 工具組為基礎所建立的靜態網站，使用 Redoc 所 render 出來的 OpenAPI 頁面，其左邊選單連結無法正常運作：點連結之後無法跳到對應的內容所在位置。
此問題花了我不少時間，是因為剛開始，我用來開發和測試的電腦並沒有任何異狀。直到有人反映他的電腦上面看到的網頁出現問題，我才進行後續的更多測試，並發現一些我到現在還是無法解釋的情形：三台電腦，其中一台 Windows Server 2019 沒有上述問題，另外兩台，分別是 Ubuntu 20.x 和 Windows 10，操作 Redoc 生成的頁面時則未出現上述狀況。然而這三台電腦上面的 Chrome 版本都一樣已經更新到最新版本，為何瀏覽 Redoc 生成的網頁時有這種差異，實在令人費解。排查過程中，花了不少時間去懷疑 Chrome 插件、防火牆等因素，最後並沒有發現明確的關聯。
解決方式
有關此狀況的成因、相關 issues 連結，以及我建立的展示頁面（包含重現問題的範例，以及修正後的範例），都已經整理在這篇筆記：Redoc side menu woes with Bootstrap CSS 5.x。雖然那篇筆記是以英文撰寫，但我想應該不難懂。其中也附上了我的範例原始碼的 GitHub 連結，可直接看原始碼。
簡單來說，我採用比較土的方法來逐漸縮小「嫌疑犯」的範圍，最終判斷是 Bootstrap CSS 5.x 導致 Redoc 生成的 OpenAPI 頁面的左邊選單連結無法正常運作。於是我自行建立一個給 Redoc 專用的 layout，把 Docsy 預設使用的 Bootstrap CSS v5.x 換成了 v4.x 的版本，然後加上一些其他版面微調，便解決了這個問題。
我的作法並沒有直接解決 Bootstrap CSS 5.x 實際上造成問題的 code，而只是避開問題而已。
先這樣吧。（等前端高手根治此問題 😀)
沒有留言: