MkDocs Roamlinks + Backlink Pass¶
概念概覽
核心實作¶
核心知識¶
核心實作¶
backlink_pass.py 掃描所有 docs/concepts/ 下的 Markdown 文件，建立反向索引，在每篇文章末尾自動注入「被哪些文章引用」的 Backlinks 區塊。
mkdocs-roamlinks-plugin 讓 MkDocs 能辨識 [[WikiLink]] 語法，在 mkdocs.yml 的 plugins 區塊加入後即可使用：
問題與限制¶
- 原始知識庫只有單向連結（A → B），讀者無法從 B 發現 A
- roamlinks 允許作者用 Obsidian 語法寫作，降低心智負擔
- backlink_pass 需在 CI 或 pre-commit 階段執行，否則 backlinks 不會更新
經驗教訓¶
-
先安裝 mkdocs-material synchronously 避免依賴競態問題
-
backlink 注入應放在文章末尾固定區塊，避免污染正文語義
-
roamlinks plugin 與 backlink_pass 是互補的：前者解決寫作便利性，後者解決導航完整性
常見陷阱¶
-
mkdocs-roamlinks 需要與 mkdocs-material 版本相容，安裝順序有影響
-
backlink_pass 若在文章已有 Backlinks 區塊時重複執行會產生重複內容，需要冪等設計
相關概念¶
- Knowledge Consolidation Pass
- obra/knowledge-graph 語義索引整合
- obsidian-claude-code
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- Obsidian Backlink + MkDocs Roamlinks — 共享：
backlink,knowledge-management,mkdocs/ 獨特：documentation,wikilink - Backlink Pass — 共享：
backlink,knowledge-management,wiki/ 獨特：graph - MkDocs Knowledge Wiki Enhancement — 共享：
knowledge-management,mkdocs,wiki/ 獨特：backlinks,roamlinks - Obsidian + MkDocs Knowledge Management — 共享：
knowledge-management,mkdocs,obsidian/ 獨特：github-pages,wikilink - Backlink System（雙向連結） — 共享：
backlink,wiki/ 獨特：bidirectional-links,knowledge-graph
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-11 | a0379709-073f-4231-a61f-87b8486559f7 | 本 session 實作了 backlink_pass.py 與 mkdocs-roamlinks-plugin，將知識庫從單向連結升級為雙向 [[Wikilink]] 連結體系 |