MkDocs Roamlinks Plugin¶
概念概覽
核心問題¶
核心知識¶
核心問題¶
原本 MkDocs 只支援 Markdown 標準連結 [text](path.md)，跨文件的語義連結難以維護，且與 Obsidian 生態不兼容。
解法¶
安裝 mkdocs-roamlinks-plugin，在 mkdocs.yml 加入 plugin 設定後，即可在 Markdown 中直接寫 [[概念名稱]]，插件會自動解析為正確的相對路徑連結。
注意事項¶
- 需搭配
backlink_pass.py才能真正實現雙向連結（roamlinks 只解決「寫法」，不自動產生反向連結） - 安裝後需重新 build，舊有單向連結文件不會自動升級
經驗教訓¶
-
roamlinks 解決的是「寫法兼容性」問題，雙向連結的「反向索引」仍需額外腳本處理
-
MkDocs 插件安裝後需重新同步 requirements-docs.txt 才能在 CI 中生效
常見陷阱¶
-
僅安裝 plugin 不等於有雙向連結，反向 backlink 需要 backlink_pass.py 另外掃描注入
-
[[Wikilink]] 名稱需與文件標題或 slug 完全匹配，否則解析失敗
相關概念¶
- Backlink Pass
- Backlink System（雙向連結）
- Obsidian + MkDocs Knowledge Management
- Semantic Knowledge Graph CI Integration
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- Obsidian Backlink + MkDocs Roamlinks — 共享：
documentation,knowledge-management,mkdocs/ 獨特：backlink,obsidian - MkDocs Knowledge Graph Enhancement — 共享：
mkdocs,wikilink/ 獨特：backlinks,knowledge-graph - MkDocs Knowledge Wiki Enhancement — 共享：
knowledge-management,mkdocs/ 獨特：backlinks,roamlinks - MkDocs Roamlinks + Backlink Pass — 共享：
knowledge-management,mkdocs/ 獨特：backlink,obsidian - Obsidian + Claude Code 知識庫整合 — 共享：
knowledge-management,wikilink/ 獨特：backlinks,obsidian
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-11 | a0379709-073f-4231-a61f-87b8486559f7 | 此 session 實作了 mkdocs-roamlinks-plugin，讓 MkDocs 知識庫支援 Obsidian 風格的 [[Wikilink]] 雙向連結語法。 |