MkDocs Knowledge Graph Enhancement¶
概念概覽
問題根源¶
核心知識¶
問題根源¶
現有 wiki 系統的核心缺陷：連結為單向（A→B，但 B 不知道 A 指向它）、概念碎片化（相似主題散落多頁）、無語義索引（只能關鍵字搜尋）。
三階段改善方案¶
Phase 1 — 低風險高回報
- backlink_pass.py：掃描所有 Markdown，建立反向連結索引，在每篇文章底部自動注入「被哪些文章引用」區塊，解決單向連結問題
- mkdocs-roamlinks-plugin：允許 [[ConceptName]] Wikilink 語法，讓作者不必寫完整相對路徑
Phase 2 — 關鍵能力升級
- 整合 obra/knowledge-graph 作為 CI 步驟，對所有文件產出語義嵌入索引
- 在 wiki_manager.py 概念提取階段加入「語義重複檢查」：新概念寫入前先計算餘弦相似度，若與現有概念 >0.85 則提示合併，避免碎片化
Phase 3 — 視覺化
- 將 knowledge-graph.md 改為互動式語義圖譜（D3.js 或 Mermaid）
- Hot cache：高頻訪問概念預載入向量，降低查詢延遲
安裝方式¶
經驗教訓¶
-
單向連結是知識庫最常見的隱性問題，backlink_pass.py 後處理比改寫原始文件侵入性更低
-
語義重複檢查要在寫入前做，而非事後整理，才能防止碎片化累積
-
mkdocs-roamlinks-plugin 讓 Wikilink 語法與 MkDocs 共存，降低貢獻者心智負擔
常見陷阱¶
-
mkdocs-material 若版本衝突需重新安裝（pip install mkdocs-material 同步安裝）
-
余弦相似度閾值 0.85 需根據領域調整，技術文件可設高一點（0.88-0.90）
-
backlink 注入若用 mkdocs hooks 做，需確保在 on_page_markdown 階段執行，避免影響 TOC 生成
相關概念¶
- Claude Code Channels vs Orchestration Layer
- Go Test Coverage -coverpkg Flag
- Obsidian + Claude Code 知識庫整合
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- MkDocs Roamlinks Plugin — 共享：
mkdocs,wikilink/ 獨特：documentation,knowledge-management - MkDocs Knowledge Wiki Enhancement — 共享：
backlinks,mkdocs/ 獨特：knowledge-management,roamlinks - obra/knowledge-graph 語義索引整合 — 共享：
knowledge-graph/ 獨特：ci,obra - Obsidian Backlink + MkDocs Roamlinks — 共享：
mkdocs,wikilink/ 獨特：backlink,documentation - Obsidian + MkDocs Knowledge Management — 共享：
mkdocs,wikilink/ 獨特：github-pages,knowledge-management
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-11 | a0379709-073f-4231-a61f-87b8486559f7 | 設計並實作三階段知識圖譜強化方案：backlink 雙向連結、Wikilink 語法支援、語義重複檢查 |