Backlink System（雙向連結）

概念概覽

問題根源

核心知識

問題根源

傳統 MkDocs wiki 的連結是單向的：A 連到 B，但 B 頁面無法知道有哪些頁面連到自己。這導致知識孤島和概念碎片化。

backlink_pass.py 的設計邏輯

1. 掃描所有 docs/concepts/*.md 文件
2. 解析每個文件中的 [[Wikilink]] 或 [text](path) 連結
3. 建立反向索引 Map（被連結頁面 → 所有連到它的頁面列表）
4. 在每個頁面底部自動注入「Backlinks」區塊

與 Obsidian 的對應關係

• Obsidian 原生支援 backlink panel
• backlink_pass.py 是在 MkDocs 靜態生成管線中模擬此功能
• 需要在 mkdocs build 前作為 pre-processing step 執行

在 CI 管線的位置

[wiki_manager.py 提取概念] → [backlink_pass.py 建立反向索引] → [mkdocs build] → [GitHub Pages deploy]

經驗教訓

• 雙向連結是知識圖譜品質的基礎設施，缺少它等於知識只能從上往下流，無法橫向發現相關概念

• pre-processing script 比 MkDocs plugin 更靈活，可以在 build 前修改 Markdown 原始碼

常見陷阱

• backlink 注入必須在 mkdocs build 之前執行，順序錯誤會導致 backlink 區塊消失

• 自動注入的 backlink 區塊若無去重邏輯，同一來源頁面可能重複出現

相關概念

• MkDocs Roamlinks Plugin
• Obsidian + Claude Code 知識庫整合
• Semantic Knowledge Graph CI Integration

相關視角

以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：

• Backlink Pass — 共享：backlink, wiki / 獨特：graph, knowledge-management
• MkDocs Roamlinks + Backlink Pass — 共享：backlink, wiki / 獨特：knowledge-management, mkdocs
• MkDocs Knowledge Wiki Enhancement — 共享：wiki / 獨特：backlinks, knowledge-management
• obra/knowledge-graph 語義索引整合 — 共享：knowledge-graph / 獨特：ci, obra
• Obsidian Backlink + MkDocs Roamlinks — 共享：backlink / 獨特：documentation, knowledge-management

來源 Sessions

日期	Session	貢獻摘要

| 2026-04-11 | a0379709-073f-4231-a61f-87b8486559f7 | 設計並實作 backlink_pass.py，解決知識庫文章只有單向連結、缺乏反向索引的根本問題。 |

---

本概念頁面由 Semi-Brain Wiki 系統自動維護

最後更新: 2026-04-11