Backlink Pass¶
概念概覽
問題背景¶
核心知識¶
問題背景¶
知識庫文件 A 連結到 B，但 B 不知道自己被 A 引用。當文件數量增多，語義關聯形成孤島，難以發現相關概念。
backlink_pass.py 運作機制¶
- 掃描所有
.md文件，建立「誰引用了誰」的正向索引 - 反轉索引 → 得到「誰被誰引用」的反向索引
- 在每個文件底部自動插入
## Backlinkssection，列出所有引用來源
# 偽代碼示意
forward_links = parse_all_links(docs_dir) # {source: [targets]}
backlinks = invert(forward_links) # {target: [sources]}
for doc, sources in backlinks.items():
inject_backlink_section(doc, sources)
整合方式¶
- 作為
wiki_manager.py的後處理步驟執行 - 或作為獨立 CI 步驟在 MkDocs build 之前執行
經驗教訓¶
-
反向連結注入必須在 MkDocs build 之前執行，否則 HTML 輸出不含 backlink
-
需要 idempotent 設計：重複執行不能產生重複的 backlink section
常見陷阱¶
-
若文件使用相對路徑與絕對路徑混用，link 解析容易產生重複或遺漏
-
backlink section 需加特殊 marker comment 以便識別舊內容並覆蓋，避免累積
相關概念¶
- MkDocs Roamlinks Plugin
- Obsidian + MkDocs Knowledge Management
- Semantic Knowledge Graph CI Integration
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- Backlink System（雙向連結） — 共享：
backlink,wiki/ 獨特：bidirectional-links,knowledge-graph - MkDocs Roamlinks + Backlink Pass — 共享：
backlink,knowledge-management,wiki/ 獨特：mkdocs,obsidian - MkDocs Knowledge Wiki Enhancement — 共享：
knowledge-management,wiki/ 獨特：backlinks,mkdocs - obra/knowledge-graph 語義索引整合 — 共享：
graph,knowledge/ 獨特：ci,knowledge-graph - Obsidian Backlink + MkDocs Roamlinks — 共享：
backlink,knowledge-management/ 獨特：documentation,mkdocs
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-11 | a0379709-073f-4231-a61f-87b8486559f7 | 此 session 設計並實作了 backlink_pass.py，解決知識庫文件單向連結問題，自動在被引用的文件底部注入「被哪些文件引用」的反向索引。 |