開發測試與新增套件

這篇是 docusaurus-kit 的維護筆記：本地怎麼跑、測試怎麼分層、新增套件要準備什麼，以及網站與套件之間怎麼協作。

環境需求

工具	版本
Node.js	>= 20.19
pnpm	12.4（透過 corepack）
Docusaurus	3.8+，測試以 3.10 為主
React	18 或 19，測試以 19 為主

corepack enable pnpm
pnpm install

pnpm-workspace.yaml 有一個供應鏈策略：新發佈的套件預設要等 24 小時才會被解析，Pele 例外。這是為了降低剛發佈的套件被供應鏈攻擊的風險，同時保留立即採用 Pele 修復的能力。

常用指令

指令	用途
pnpm build	建置所有 packages
pnpm typecheck	型別檢查
pnpm test	單元測試；theme 會先 build
pnpm check	Biome format + lint
pnpm check:fix	自動修正 Biome 問題
pnpm playground	啟動 fixture site（http://localhost:3100）
pnpm playground:build	建置 fixture site
pnpm test:e2e	對現有 fixture build 跑 Playwright
pnpm check:ci	完整本地 gate

test:e2e 不會幫你建置 fixture；要先跑 pnpm playground:build。Playwright 使用系統 Chrome（channel: 'chrome'），不是另外下載的 Chromium。

測試分層

單元測試

• theme-pele：檢查 plugin name、Mermaid theme component、client stylesheet、供 swizzle 的 source path 是否存在。Theme 的真正渲染交給 fixture site 與 Playwright。
• remark-obsidian-kanban：用 unified + remark-parse + remark-frontmatter + remark-gfm + remark-wiki-link 組出 pipeline，檢查欄位、卡片、狀態、wikilink、settings 區塊與非看板文件。
• rehype-obsidian-tasks：用 remark-rehype + rehype-stringify 檢查 [-]、[/]、GFM checkbox、loose list 與一般清單。

Fixture site

examples/playground 是三個套件共同的 integration test：

• docs/index.md：Pele 圖表，涵蓋常見圖表類型。
• docs/kanban.md：Obsidian 看板。
• docs/tasks.md：任務狀態。
• docusaurus.config.ts：markdown.format: 'detect'、markdown.mermaid: true、theme 與 remark/rehype plugin 設定。

Playwright

e2e/playground.spec.ts 檢查：

• 7 張圖都變成 svg.pele。
• 寬圖有 2 個 zoom control。
• zoom control 不遮住 SVG。
• dark mode 切換後 --pele-bg 改變，圖表仍可見。
• 沒有 page error。

這一層是必要的：theme 套件就算單元測試全過，也可能在 Docusaurus 的 theme resolution 或 SSR 階段壞掉。

Package 結構

theme-pele

packages/theme-pele/
├── src/
│   ├── index.ts                 # Docusaurus plugin entry
│   ├── types.ts                 # themeConfig.pele 型別
│   ├── theme/Mermaid/index.js   # 覆寫 Docusaurus Mermaid component
│   └── client/
│       ├── index.ts             # 載入 CSS
│       └── pele.css             # --pele-* 對應 --ifm-*
├── scripts/copy-assets.mjs
├── test/theme.test.mjs
└── lib/                         # build 產物，gitignored

lib/ 由 pnpm build 產生，prepack 會再建一次；不要手動 commit。

remark / rehype plugin

packages/remark-obsidian-kanban/
├── src/index.js
├── index.d.ts
├── test/kanban.test.mjs
└── README.md

rehype-obsidian-tasks 結構相同。兩個 plugin 都是 CJS 進入點，透過 exports 提供 types 與 default。

新增一個套件

1. 建立目錄與 package.json
   • name、version、description、license、repository.directory
   • files 只放真的要發佈的檔案
   • publishConfig.access: "public"
   • engines.node 與 repo 一致
2. 寫 README
   • 相容版本表（Docusaurus / React / Node）
   • 安裝指令
   • 最小可執行範例
   • 已知限制
3. 定義型別
   • 對外選項要有 .d.ts，不要讓使用者只能讀原始碼。
4. 加測試
   • 用 unified 測 AST 行為，不要只測字串包含。
   • Theme 套件要加 fixture 頁面與 Playwright 檢查。
5. 放進 playground
   • 加 docs 頁面與 docusaurus.config.ts 設定。
   • 確認 pnpm playground:build 與 pnpm test:e2e 都過。
6. 加 changeset
   • pnpm changeset，選擇 minor 或 patch。
7. 第一次發佈
   • 互動式 pnpm --filter <package> publish --access public。
   • 到 npm 設定 trusted publisher。
8. 讓 CI 接手
   • 之後只透過 version PR 發佈，不再本地 publish。

跨 repository 協作

網站 repository 是 consumer，套件 repository 是 producer。這個邊界要守住：

• 不要在網站 repository 發佈套件。
• 不要在套件 repository 放入任何站台的內容、路徑或政策。
• 網站升級套件版本時，單獨開 commit，不要跟內容變更混在一起。

需要本地同時改兩邊時，可以用：

• yalc：把本地 package 連結進網站，適合短期 dogfood。
• canary release：發一個 pre-release 版本，讓網站安裝。
• npm link：最快，但 peer dependency 與 hoisting 容易出現落差。

常見地雷

問題	原因	解法
Kanban 變成空白或 HTML 被吃掉	MDX 不接受 raw HTML	markdown.format: 'detect'
看板卡片 wikilink 沒變成連結	remarkKanban 在 remark-wiki-link 之前	把 kanban 放在後面
看板頁出現 broken anchors	## 被替換成 HTML，TOC 仍指向舊 heading	hide_table_of_contents: true
圖表沒出現	只裝 theme，沒開 markdown.mermaid	兩個都要設
圖表仍是 Mermaid 樣式	@docusaurus/theme-mermaid 還在 themes 裡且排在後面	移除舊 theme，或把 Pele 放最後
CI 無法建立 version PR	repo 不允許 Actions 建立 PR	開啟 Actions 的 PR 權限
npm 發佈 404	新套件尚未第一次發佈或沒有 trusted publisher	先互動式發佈，再設 trust

發版檢查清單

pnpm check:ci
pnpm changeset
git add -A
git commit -m "feat: ..."
git push

合併 version PR 後確認：

• npm latest 是預期版本。
• npm view <package>@<version> dist.attestations 有 provenance。
• GitHub 有對應的 git tag。
• Release workflow 是 success。

下一步

• 持續把站台專用邏輯留在 consumer，套件只保留通用 API。
• 評估其他站台外掛是否能拆出資料中立的 API；在還沒拆開前，不急著搬。
• 補更多圖表類型的 fixture，降低 Pele 升級時的視覺回歸風險。

系列文章

• 01 docusaurus-kit 專案總覽
• 02 docusaurus-theme-pele 與 Mermaid 遷移
• 03 Obsidian 外掛 Kanban 與 Tasks
• 04 GitHub Actions 與 npm 信任發佈
• 06 docusaurus-kit 版本與變更記錄

參考

• docusaurus-kit README
• ADR 0001