跳至主要内容

[Docusaurus] Plugin 使用筆記

本文記錄在 Docusaurus 專案中使用的各種 remark 插件，特別是針對 Obsidian 整合所開發或配置的插件。

部分外掛由 docusaurus-kit 發佈到 npm；站內 plugins/ 版本仍在使用，npm 版本已可用。各節標示目前的建議用法與切換狀態。

docusaurus-kit 套件​

套件版本類型用途
docusaurus-theme-pele0.1.1theme以 Pele 取代 Mermaid renderer
remark-obsidian-kanban0.3.0remarkObsidian Kanban 轉靜態看板
rehype-obsidian-tasks0.2.1rehype[-] / [/] 任務狀態

來源與發佈流程見 01 docusaurus-kit 專案總覽、04 GitHub Actions 與 npm 信任發佈。

核心外掛與主題​

Wikilink in Docusaurus 插件支援 [[Document Filename|Display Title]] 這樣的 Wiki 內部文件連結語法。

主要優勢：

  • 動態解析：不需指明檔案絕對位置，產出文件網站時動態搜尋
  • 重構友善：重構資料夾結構或搬移檔案時，較不會造成連結失效
  • Obsidian 相容：與 Obsidian 的 Wiki-Link 語法完全相容

配置範例：

[remarkWikiLink, {
  pageResolver: createPageResolver(fileMap),
  hrefTemplate: (permalink) => `/${permalink}/`,
  aliasDivider: '|'
}]

docusaurus-theme-pele​

以 Pele 取代 @docusaurus/theme-mermaid 的 Docusaurus theme。仍使用 mermaid 圍欄語法，但 renderer 換成體積較小、同步渲染、可用 CSS 變數切換主題的 Pele。

設定只有兩件事：markdown.mermaid: true 與 themes: ['docusaurus-theme-pele']；舊的 @docusaurus/theme-mermaid、mermaid、@mermaid-js/layout-elk 可以移除。詳細遷移與相容性見 02 docusaurus-theme-pele 與 Mermaid 遷移。

remark-obsidian-kanban​

已從站內 plugins/ 抽到 docusaurus-kit，站台直接使用 npm 版本 0.3.0。Plugin Remark Obsidian Kanban 保留為詳細使用與實作筆記。

核心功能：

  • 自動識別 kanban-plugin: board frontmatter
  • ## 轉欄位、清單項目轉卡片，欄位標題顯示卡片數
  • 可選 pageResolver / hrefTemplate 解析卡片內的 wikilink；不提供時仍可渲染
  • 卡片狀態 [ ]、[x]、[-]、[/] 會轉成對應 class 與 data-task
  • 圖片、Markdown 連結與縮排內容保留
  • 自動移除 Obsidian 的 kanban:settings 區塊

注意：外掛輸出 raw HTML，Docusaurus 需設 markdown.format: 'detect'；看板頁請用 frontmatter hide_table_of_contents: true，不要用 CSS 隱藏 TOC。

rehype-obsidian-tasks​

將 Obsidian 的 [-]（取消）與 [/]（進行中）轉成 GFM task item 的 rehype 外掛，npm 版本 0.2.1。

核心功能：

  • 保留標準 GFM [ ] / [x] 行為
  • 加上 task-list-item--cancelled、task-list-item--in-progress 與 data-task
  • 父層清單加 contains-task-list
  • 支援 tight list 與 loose list
  • 只處理 task item 的 class/attribute 與 checkbox，視覺由站台 CSS 決定

安裝、設定與兩個外掛一起用的範例見 03 Obsidian 外掛 Kanban 與 Tasks。

remark-story-map​

Geo Story Map 官方發布的 Docusaurus remark 插件，負責把兩種地理圍欄區塊轉成互動式地圖。

核心功能：

  • 自動識別 story-map（故事地圖）與 leaflet（純地圖）兩種程式碼區塊
  • markerFolder / noteFolder 遞迴掃描 Vault，既有筆記的 location、mapmarker、mapzoom 直接沿用
  • 建置期只輸出空 host 容器，Leaflet 僅在瀏覽器端動態載入（SSR／build 不會建立實例）
  • 單一 client 生命週期依明確的 story / map 判別式掛載，同一頁不會初始化兩次 Leaflet

配置範例：

// plugins/story-map-client/index.js
module.exports = function storyMapClientPlugin() {
  return {
    name: 'story-map-client',
    getClientModules() {
      return [require.resolve('@story-map/remark-story-map/client')];
    },
  };
};
// docusaurus.config.ts
const storyMapOptions = {
  vaultRoot: __dirname,                        // 掃描標記來源的 Vault 根目錄
  resolveNoteHref: (vaultRelativePath) =>      // 網址交給站台既有索引決定
    contentLinkIndex.resolve(vaultRelativePath)[0]?.route,
  leafletDefaults: { theme: 'auto' },          // 僅供 leaflet 區塊使用
};

remarkPlugins: [[remarkStoryMap, storyMapOptions]]

react 與 react-dom 是 peer dependency，兩者都必須是 React 19。完整安裝、主題橋接與移除舊 runtime 的步驟見 Plugin Remark Obsidian Leaflet。

docusaurus-plugin-album​

自製的 Docusaurus 攝影相簿外掛程式（位於 plugins/docusaurus-plugin-album/），以微包裝模式（Wrapper Pattern）封裝 @docusaurus/plugin-content-blog，為相簿頻道打造專屬的影像敘事與互動瀏覽體驗。

核心功能：

  • Pinterest 瀑布流：長寬比自適應卡片錯落分欄，滑鼠懸停（Hover）平滑浮現標題、地點與相簿系列
  • Google Photos 時光軸：右側固定膠囊滑桿，即時年份感應與平滑錨點跳轉
  • 沉浸式 Hero Header：文章內頁滿版封面橫幅與中繼資料徽章
  • 原生全螢幕相片燈箱：零依賴輕量 Lightbox，支援鍵盤導航並嚴格排除作者大頭貼（Avatar Exclusion）
  • 乾淨解耦：自帶 validateOptions 與 Theme Components，無需在主設定檔撰寫判斷式

配置範例：

// docusaurus.config.ts
[
  path.resolve(__dirname, 'plugins/docusaurus-plugin-album'),
  {
    id: 'album',
    routeBasePath: 'album',
    path: 'blog.album',
    remarkPlugins: createBlogRemarkPlugins({ id: 'album', path: 'blog.album' }),
  },
]

詳細架構設計與演進過程見 Album 相簿部落格：完工成果與路徑一插件化實作。

已移除外掛​

remark-obsidian-leaflet 與 remark-oembed 的移除原因、替代方案與站台外掛沿革，整理在 Docusaurus 版本與變更記錄。

延伸閱讀​