MkDocs Knowledge Wiki Enhancement¶
概念概覽
核心問題診斷¶
核心知識¶
核心問題診斷¶
現有 semi-brain wiki 的主要缺陷： - 概念連結為「單向」—— A 連到 B，但 B 頁面不知道有人連結它 - 概念碎片化：同一主題可能被分散到多個不同命名的頁面 - 無語義索引，搜尋只能靠全文比對
Phase 1 修復（低風險高回報）¶
1. backlink_pass.py — 後處理腳本，掃描所有 .md，建立反向連結並注入「Referenced by」區塊
2. mkdocs-roamlinks-plugin — 讓文章可用 [[WikiLink]] 語法，自動解析為相對 URL
Phase 2 語義升級¶
3. obra/knowledge-graph 整合進 CI — 產出語義索引 JSON，供搜尋與視覺化使用
4. wiki_manager.py 概念提取階段加入「語義重複檢查」— 用 embedding 相似度偵測重複概念，防止碎片化
Phase 3 展示層¶
- knowledge-graph.md 改為互動式語義圖譜視覺化
- Hot cache 機制：預快取高頻概念的 embedding
經驗教訓¶
-
單向連結是 wiki 知識腐爛的根本原因，backlink 是最高 ROI 的修復
-
概念碎片化需在寫入時（提取階段）就用語義相似度攔截，事後整併成本很高
-
mkdocs-roamlinks-plugin 讓作者用 Obsidian 習慣的 [[WikiLink]] 寫法，降低寫作摩擦
常見陷阱¶
-
mkdocs-material 安裝可能有 pip 環境問題，需同步安裝確認（background task 可能掩蓋失敗）
-
obra/knowledge-graph 作為 CI 步驟需評估執行時間，避免拖慢 PR merge
最佳實踐¶
-
先做 backlink_pass.py（純後處理，零破壞風險），再做語義升級
-
語義重複閾值建議從 0.85 cosine similarity 開始，根據實際碎片率調整
相關概念¶
- knowledge-graph-ci----dangling---
- Obsidian + Claude Code 知識庫整合
- wiki-manager-concept-extraction----dangling---
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- MkDocs Roamlinks + Backlink Pass — 共享：
knowledge-management,mkdocs,wiki/ 獨特：backlink,obsidian - MkDocs Knowledge Graph Enhancement — 共享：
backlinks,mkdocs/ 獨特：knowledge-graph,semantic-index - Backlink Pass — 共享：
knowledge-management,wiki/ 獨特：backlink,graph - MkDocs Roamlinks Plugin — 共享：
knowledge-management,mkdocs/ 獨特：documentation,wikilink - Obsidian + MkDocs Knowledge Management — 共享：
knowledge-management,mkdocs/ 獨特：github-pages,obsidian
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-11 | a0379709-073f-4231-a61f-87b8486559f7 | 本 session 確立了以 backlink_pass.py + mkdocs-roamlinks-plugin 解決單向連結問題的具體方案，並排定三階段優化路線圖 |