Obsidian 整合功能展示

Obsidian 是一款以本地 Markdown 檔案為核心的知識管理工具。Astro Modular 這個主題將 Obsidian 的語法原生帶入靜態網站，讓你在 Vault 裡怎麼寫，網站上就怎麼顯示。

這篇文章是一份完整的功能展示，涵蓋所有支援的 Obsidian 特性。

1. Callout 方塊

Obsidian 的 Callout 語法以 >[!type] 開頭，Astro Modular 將其渲染為帶有色彩和圖示的提示方塊。

2. Wikilinks

在 Obsidian 和 Astro Modular 中，你可以使用 [[文章名稱]] 語法建立內部連結。系統會自動解析路徑並生成正確的 URL。

範例：AI 代理瀏覽器控制 這篇文章探討了 agent 如何看見瀏覽器畫面的問題。

你也可以為 wikilink 加上自訂顯示文字，例如 SuperPortia 專案全景 ，讓連結文字更具可讀性。

3. 程式碼區塊

展示多語言語法高亮。程式碼區塊支援行號顯示與複製按鈕。

Python — 呼叫 SuperPortia Agent SDK：

from superportia import AgentClient

client = AgentClient()
results = client.search_brain(query="fleet deployment")

for entry in results:
    print(f"[{entry.score:.2f}] {entry.title}")

TypeScript — 同樣的操作，型別安全版本：

import { AgentClient } from 'superportia';

const client = new AgentClient();
const results = await client.searchBrain({ query: 'fleet deployment' });

results.forEach(entry => {
  console.log(`[${entry.score.toFixed(2)}] ${entry.title}`);
});

Bash — 直接透過 REST API 呼叫：

curl -X POST https://ub.superportia.dev/brain/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "fleet deployment"}'

YAML — 設定範例：

# astro.config.mjs 相關設定
integrations:
  - obsidianModular({
      vault: './src/content',
      wikilinks: true,
      callouts: true,
      mermaid: true,
    })

4. 表格

Markdown 標準表格語法，支援靠左、置中、靠右對齊。

5. 引用

標準 Markdown 引用語法，適合標示名言或重要論述。

「這才是我成立這家公司完整的閉環。我用順了，對外服務時，外部大量使用者才會順。」
— 夏哥

The best documentation is the one that stays in sync with the code — automatically.
— Astro Modular 設計理念

6. 清單

有序清單

1. 第一步：建立 Obsidian vault
2. 第二步：安裝 Astro Modular
3. 第三步：設定 content collection
   1. 子步驟：定義 schema
   2. 子步驟：建立 glob loader
4. 第四步：部署到 Cloudflare Pages

無序清單

• Vault 是 governance SSoT
• Cloud UB 是 agent 可搜知識庫
• GitHub 是 code SSoT
  • 11 個 repos
  • 每個 repo = 一個可部署單元
  • 每個 repo 有獨立的 CI/CD pipeline

任務清單

• 設定 Obsidian Vault
• 安裝 Astro Modular 主題
• 測試 Callout 渲染
• 驗證 Wikilinks 解析
• 加入 Mermaid 圖表支援
• 建立 Graph View 頁面

7. 行內格式

Markdown 支援豐富的行內格式，讓文章排版更靈活：

粗體、斜體、粗斜體、刪除線、行內程式碼、高亮標記

組合使用範例：在 SuperPortia 的 worker.js 中，所有進入 Dock 的條目都會被 同步 非同步地標記為 pending，等待後續分類。

8. 媒體嵌入

影片嵌入

Obsidian 語法 ![[video.mp4]] 會在網頁上渲染為帶有播放控制列的 HTML5 影片播放器。

音訊嵌入

![[sound.wav]] 會渲染為帶有播放、暫停、音量控制的音訊播放器。

PDF 嵌入

![[document.pdf]] 嵌入完整 PDF，加上 #page=2 可指定起始頁面。

9. 圖片 Gallery

多張圖片連續排列時，Astro Modular 自動組成 Gallery 模式，支援點擊放大與左右切換。

Obsidian wikilink 語法同樣支援圖片大小控制：![[mountains.png|600]]

10. 分隔線

三個以上的連字號 --- 或星號 *** 會渲染為水平分隔線。

11. 數學公式（KaTeX）

Astro Modular 整合 KaTeX，支援 LaTeX 語法的數學排版。

行內公式：著名的質能等價公式 $E = mc^2$，以及歐拉恆等式 $e^{i\pi} + 1 = 0$。

Display 公式（獨立一行，置中顯示）：

矩陣：

12. Mermaid 圖表

Mermaid 是一種以文字描述圖表的語言，Astro Modular 支援在 code block 中使用 mermaid 語言標籤直接渲染。

流程圖：

flowchart LR
    A[Obsidian Vault] -->|glob loader| B[Astro Content Collection]
    B --> C{Build}
    C -->|SSG| D[Static HTML]
    C -->|SSR| E[Edge Worker]
    D --> F[Cloudflare Pages]
    E --> F

序列圖：

sequenceDiagram
    participant User
    participant Obsidian
    participant GitHub
    participant CF as Cloudflare Pages

    User->>Obsidian: 編寫文章
    Obsidian->>GitHub: git push
    GitHub->>CF: webhook trigger
    CF->>CF: npm run build
    CF-->>User: 新文章上線

Git Graph：

gitGraph
   commit id: "init"
   branch feature/obsidian
   checkout feature/obsidian
   commit id: "add callouts"
   commit id: "add wikilinks"
   checkout main
   merge feature/obsidian id: "release v1.0"

13. Backlinks 與 Graph View

每篇文章底部會自動顯示 LinkedMentions（Backlinks），列出所有引用這篇文章的其他文章。這讓讀者可以探索相關內容，形成知識網絡。

LocalGraph 則以視覺化節點圖呈現文章之間的連結關係，讓你一眼看出哪些主題彼此相關。

14. 總結

這篇文章展示了 Astro Modular 對 Obsidian 語法的完整支援：

所有格式在 Obsidian 編輯器和 Agentic 網站上看起來一致，實現了真正的「寫一次，到處發布」。你的 Vault 就是你的 CMS。