從 MkDocs 遷移與外掛相容性

Zensical 由 Material for MkDocs 的原班人馬打造，相容性是核心目標。多數現有的 MkDocs 專案不需要修改就能建置。

相容範圍

循序漸進的遷移方式

你不必改設定或流程，因為 Zensical 讀得懂 mkdocs.yml，所以同一個專案可以用兩種指令建置：

mkdocs build
zensical build

建議的步驟：

1. 保留現有 MkDocs 的正式佈署，不要動它。
2. 用 Zensical 讀同一份 mkdocs.yml 建置。
3. 比對代表性的頁面、導覽、搜尋與客製化內容。
4. 確認所有依賴的 MkDocs 外掛都有支援。
5. 有把握之後，才把本機與 CI 的指令換成 Zensical。

因為 MkDocs 的建置是「安全網」，所以隨時可以退回。想繼續用 mkdocs.yml 多久都可以，改用 zensical.toml 並不是必要的。

尚未支援的設定

下列 mkdocs.yml 設定 Zensical 目前尚不支援：

• remote_branch
• remote_name
• exclude_docs
• draft_docs
• not_in_nav
• hooks

指令差異

主題變體：classic 與 modern

Zensical 提供兩種變體，兩者的 HTML 結構相同：

[project.theme]
variant = "classic"   # 或 "modern"

• classic：保留 Material for MkDocs 的外觀。遷移既有專案，或自訂的 CSS／JavaScript 依賴原本外觀時，建議使用。
• modern：新的外觀。

模板與覆寫

Zensical 使用 MiniJinja（以 Rust 寫的模板引擎），而不是 Jinja。MiniJinja 與 Jinja 大致相容，但沒有 Python 直譯器，不能呼叫任意的 Python 函式，請改用它提供的過濾器（filters）與測試（tests）。

Material for MkDocs 9.6.18 已完成最後的相容調整，以該版本或更新版本為基礎的覆寫通常不需修改。遷移較舊或大量客製化的覆寫時：

1. 與最新的 Material for MkDocs 模板比對。
2. 把呼叫任意 Python 函式的地方，換成支援的過濾器或測試。
3. 建置一組代表性的頁面，逐一檢查被覆寫的區塊。

已支援的外掛

Zensical 以原生實作提供下列外掛，大部分不需要另外安裝套件。設定裡的外掛若不在支援清單，會被悄悄忽略（不會載入也不會執行）；支援的外掛中，被標示為忽略的選項也會悄悄忽略，其他不認識的選項則會在解析設定時報錯。

範例（在 mkdocs.yml 與 zensical.toml 中的寫法）：

plugins:
  - tags
  - minify:
      minify_html: true

[project.plugins.tags]

[project.plugins.minify]
minify_html = true

不支援的外掛：mkdocs-gen-files

Zensical 目前不支援 mkdocs-gen-files。請把產生檔案的腳本獨立於建置之外執行（一次或定期），並把產生的檔案納入版本控制。可以用 uvx 執行腳本（這個方法需要 mkdocs.yml，zensical.toml 不適用）：

uvx --with mkdocs-gen-files python scripts/gen_ref_pages.py

相容性路線圖

這些狀態反映目前的優先順序，不代表發佈日期。

版本管理（mike）

如果你的 MkDocs 專案已經用 mike 做多版本文件，可以在遷移期間沿用。需要安裝相容的 fork（從 GitHub 安裝，需要 git）：

pip install git+https://github.com/squidfunk/mike.git

設定沿用 Material for MkDocs 的寫法：

extra:
  version:
    provider: mike

這個整合是過渡方案：fork 只會修相容性問題，不會有新功能；官方之後會提供原生的版本管理。

其他官方提到的進階功能

總結

參考資料

• MkDocs 相容性
• Migrate from MkDocs
• MkDocs plugins
• Versioning with mike
• Directives