追蹤：Material for MkDocs 2026-11-05 EOL 的因應

## 背景

Material for MkDocs 已經進入維護模式，EOL 日期寫在上游的 `SECURITY.md`：**2026-11-05**。過了那一天不再提供公開安全更新，套件本身仍留在 PyPI 與 GitHub。

現在仍有修補在進行，9.7.7（2026-07-17）修掉搜尋建議的 DOM-based XSS。這個程式庫確實會出安全問題，EOL 之後就沒有公開修補的管道。

9.7.0 起原本 Insiders 專屬的功能全部免費開放，最終版本已經是完整版，之後只修關鍵 bug 與安全問題，不加新功能。

## 腳下的框架同時也在動

- MkDocs 1.x 最後一版是 1.6.1（2024-08-30），兩年沒有新版
- MkDocs 2.0 由 encode 組織重寫（`github.com/encode/mkdocs`），PyPI 上已有 `2.0.dev0` 到 `2.0.dev3`，最新一版 2026-09-02。查 GitHub API，該 repo 的 `license` 欄位目前是 null
- 依 Material 作者的評估文，2.0 移除外掛系統、設定改用 TOML、主題系統重寫，與 Material 不相容。評估出自有利害關係的一方，其中「移到 encode」、「目前沒有授權聲明」、「1.x 兩年沒發版」這三點可以獨立查證

Zensical 是 Material 作者的接班專案，PyPI 目前 0.0.59（2026-09-03），仍在 0.0.x。

## 我們實際用到的東西

遷移成本等於這份清單裡沒有對應方案的項目數量。

**外掛**：`search`（zh、en）、`redirects`、`social`（自訂版型 `layouts/anoni.yml`、Noto Sans TC）、`privacy`（`assets_exclude`）、`git-revision-date-localized`、`blog`、`rss`、`charts`（vega-lite）

**主題功能**：`navigation.tabs`、`navigation.tabs.sticky`、`navigation.sections`、`navigation.indexes`、`navigation.path`、`navigation.top`、`search.suggest`、`search.highlight`、`search.share`、`content.action.view`、`content.action.edit`、`content.tooltips`、`content.code.copy`、`content.footnote.tooltips`、`announce.dismiss`

**其他擴充點**：
- `theme.custom_dir`（`overrides`）
- `hooks`：`hooks/latest_posts.py`、`hooks/offline_index.py`
- pymdownx 一整組：`superfences`（自訂 fence 接 `mkdocs_charts_plugin`）、`snippets`、`tabbed`、`blocks.caption`、`emoji`
- `toc` 的 `slugify` 指定 `pymdownx.slugs.slugify`，錨點行為換工具就會變
- 三語系用 `!ENV` 驅動分別建置（`run.sh`、`run_en.sh`、`run_zh-cn.sh`）
- social cards 依賴 `material[imaging]`

## 選項

1. **留著不動**。文件站是靜態產物，工具鏈凍結不影響已經上線的內容。風險落在送進讀者瀏覽器的主題 JS，EOL 之後那一類問題沒有公開修補
2. **fork Material**。授權 MIT，合法且技術上可行。實際要接手的是主題 JS 的安全修補與 Python 相依追蹤。另外那四個第三方外掛依賴 MkDocs 1.x 的外掛 API，fork 主題不解決那一層
3. **遷到 Zensical**。作者宣稱相容 MkDocs 1.x 專案，目前仍在 0.0.x。Tor 的 onion-zensical 正在做同一份相容矩陣，我們的外掛清單跟他們高度重疊
4. **換其他工具**。成本最高，現階段不評估

## 待辦

- [ ] 確認 CI 的 uv 走 `--frozen`，建置環境釘死到可重現
- [ ] 把上面的相依清單逐項對照 Zensical 的支援狀況，標出沒有對應的項目
- [ ] 追 `tpo/onion-services/onion-zensical` issue #1 的相容矩陣，省下自己從零評估
- [ ] 找到 Material 的安全公告來源並訂閱，EOL 之後仍要盯
- [ ] 觸發條件成立時重新評估

## 重新評估的觸發條件

用事件判斷，不用日期：

- Zensical 發出 1.0
- 2026-11-05 之後，Material 出現沒有修補的用戶端漏洞
- 我們用到的外掛任何一個宣告停止維護

## 參考

- [Material for MkDocs SECURITY.md](https://github.com/squidfunk/mkdocs-material/blob/master/SECURITY.md)：EOL 日期
- [9.7.7 release notes](https://github.com/squidfunk/mkdocs-material/releases/tag/9.7.7)：EOL 警語與 XSS 修補
- [Zensical 公告](https://squidfunk.github.io/mkdocs-material/blog/2025/11/05/zensical/)
- [Insiders – Now free for everyone](https://squidfunk.github.io/mkdocs-material/blog/2025/11/11/insiders-now-free-for-everyone/)
- [What MkDocs 2.0 means for your documentation projects](https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/)
- [Onion Zensical 遷移計畫](https://gitlab.torproject.org/tpo/onion-services/onion-zensical/-/issues/1)
- [Zensical](https://zensical.org/)