Obsidian Backlink + MkDocs Roamlinks¶
概念概覽
問題背景¶
核心知識¶
問題背景¶
現有 MkDocs 知識庫的連結是**單向**的：A 文章連結 B，但 B 不知道 A 的存在。這導致知識孤島，無法從 B 反向追溯到引用它的文章。
解法架構（Phase 1）¶
backlink_pass.py¶
- 掃描所有 docs/ 目錄下的 Markdown 文件
- 建立反向索引：記錄哪些文章引用了目標文章
- 在目標文章底部自動注入「被以下文章引用」區塊
- 屬於**低風險、高回報**的改造（約 2 小時工作量）
mkdocs-roamlinks-plugin¶
- 允許使用
[[ConceptName]]Wikilink 語法撰寫文章 - 作者寫作時不需要知道精確的相對路徑，降低寫作摩擦
- 與 Obsidian 的連結語法兼容，方便跨工具作業
- 安裝：
pip install mkdocs-roamlinks-plugin，在mkdocs.yml的 plugins 區塊加入roamlinks
與 Obsidian CLI 整合¶
- Obsidian 本身使用 [[Wikilink]] 作為連結語法
- mkdocs-roamlinks 讓 MkDocs 能解析相同語法，實現 Obsidian ↔ MkDocs 雙向相容
- 社群已有 Claude Code + Obsidian 整合方案，透過 Obsidian CLI 可自動化知識整理流程
經驗教訓¶
-
單向連結是知識庫「資訊孤島」的根本原因，backlink 是最直接的修復手段
-
mkdocs-roamlinks 讓寫作者不必記住精確路徑，顯著降低新增連結的門檻
-
Obsidian 的 [[Wikilink]] 語法可直接對應到 MkDocs，減少工具切換成本
常見陷阱¶
-
mkdocs-material 與 roamlinks 版本可能有相依衝突，需同步重裝確認
-
backlink 注入若直接修改原始 .md 檔案會造成 git diff 汙染，應在 build 階段動態注入
最佳實踐¶
-
先實作 backlink_pass.py 掃描注入，再加 roamlinks plugin，兩者相輔相成
-
backlink 注入應放在 CI pipeline 而非手動執行，確保每次部署都是最新狀態
-
Wikilink 目標名稱應與 slug 保持一致，避免 roamlinks 解析失敗
相關概念¶
- Knowledge Consolidation
- mkdocs-wiki-system----dangling---
- Semantic Knowledge Graph CI Integration
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- MkDocs Roamlinks Plugin — 共享：
documentation,knowledge-management,mkdocs - MkDocs Roamlinks + Backlink Pass — 共享：
backlink,knowledge-management,mkdocs/ 獨特：wiki - Obsidian + MkDocs Knowledge Management — 共享：
knowledge-management,mkdocs,obsidian/ 獨特：github-pages - Obsidian + Claude Code 知識庫整合 — 共享：
knowledge-management,obsidian,wikilink/ 獨特：backlinks,pkm - MkDocs Knowledge Graph Enhancement — 共享：
mkdocs,wikilink/ 獨特：backlinks,knowledge-graph
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-11 | a0379709-073f-4231-a61f-87b8486559f7 | 為 MkDocs 知識庫引入雙向連結（backlink）與 [[Wikilink]] 語法支援，解決單向連結導致的知識孤島問題 |