Astro Modular 內文元件參考手冊

這份手冊是 Agentic Blog 所有內文元件的完整參考，涵蓋從 Callout 方塊到 Mermaid 圖表的 25+ 個模組。無論是人工撰稿還是 AI agent 自動生成，都應以此作為排版指南。

同場加映：Obsidian 整合功能展示 示範 Obsidian 原生語法如何對應到網站渲染效果，兩篇搭配閱讀效果最佳。

1. Callout 方塊（13 種）

Callout 以 >[!type] 語法開頭，是最常用的強調元件。以下展示全部 13 種類型：

可折疊 Callout

在 type 後加 +（預設展開）或 -（預設折疊）：

2. 表格

基本比較表

對齊示範（左、置中、右）

實際範例：Claude 功能比較

3. 程式碼區塊

Python — 讀取環境變數並呼叫 API

import os
import anthropic

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}]
)

print(message.content[0].text)

TypeScript — Astro Content Collection 型別定義

import { defineCollection, z } from "astro:content";

const posts = defineCollection({
  type: "content",
  schema: z.object({
    title: z.string(),
    description: z.string(),
    date: z.date(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
    image: z.string().optional(),
    category: z.string().optional(),
    articleType: z.enum(["learning-note", "tutorial", "analysis"]).optional(),
  }),
});

export const collections = { posts };

Bash — 部署前檢查

#!/bin/bash
# 部署前驗證：確認 build 成功且沒有 TypeScript 錯誤
set -e

echo "Running type check..."
npx astro check

echo "Building site..."
npm run build

echo "Checking output size..."
du -sh dist/

echo "Deploy ready ✓"

YAML — Astro 專案設定

# astro.config.mjs 對應的設定結構
site: "https://agentic.superportia.dev"
base: "/"
integrations:
  - mdx
  - sitemap
  - tailwind
markdown:
  remarkPlugins:
    - remark-math
  rehypePlugins:
    - rehype-katex
    - rehype-mermaid

4. Mermaid 圖表

Flowchart — Blog 發布流程

flowchart LR
    A[Obsidian Vault] -->|git push| B[GitHub Repo]
    B -->|CI trigger| C[Astro Build]
    C -->|npm run build| D[dist/]
    D -->|wrangler pages deploy| E[CF Pages]
    E --> F((agentic.superportia.dev))

    style A fill:#d97757,color:#fff
    style F fill:#141413,color:#fff

Sequence Diagram — VaultCMS 工作流程

sequenceDiagram
    participant A as Author
    participant O as Obsidian
    participant G as Git
    participant CF as CF Pages
    participant R as Reader

    A->>O: 撰寫 Markdown 文章
    O->>O: 即時預覽（本地）
    A->>G: git commit + push
    G->>CF: Webhook 觸發 Build
    CF->>CF: Astro Build (2-3 min)
    CF-->>A: Build 成功通知
    R->>CF: 瀏覽文章
    CF-->>R: 靜態 HTML 回應

5. 數學公式（KaTeX）

行內公式 — 閱讀時間估算

文章的預估閱讀時間為 $t = \lceil w / 200 \rceil$ 分鐘，其中 $w$ 是文章總字數，200 是平均閱讀速度（中文每分鐘約 200 字）。

區塊公式 — 樣本標準差

計算一組文章長度的離散程度：

其中 $x_i$ 是每篇文章的字數，$\bar{x}$ 是平均字數，$n$ 是文章總數。標準差越大，表示文章長度差異越懸殊。

6. Wikilinks 與 Tags

Wikilink 範例

Wikilinks 用雙方括號語法建立站內連結，Astro Modular 會自動解析並生成正確的 URL：

• Obsidian 整合功能展示 — Obsidian 功能的完整展示文章
• SuperPortia 專案全景 — SuperPortia 整體架構概覽

行內 Tag

在文章中提及相關標籤：#astro-modular #formatting #reference

Tags 連結到對應的 tag 彙整頁面，讓讀者發現同主題文章。

7. 行內格式

Markdown 支援多種行內格式，各有適用場景：

• 粗體（**text**）：強調關鍵詞或重要概念
• 斜體（*text*）：書名、術語首次出現、輕度強調
• 粗斜體（***text***）：極度強調，謹慎使用
• 刪除線（~~text~~）：已棄用的做法或已修正的錯誤
• inline code（反引號）：函數名、指令、檔案路徑
• highlight（==text==）：掃描時需要注意的關鍵資訊

實際句子範例：

在終端機執行 npm run dev 啟動開發伺服器，預設監聽 localhost:4020。若遇到 port 衝突，在 astro.config.mjs 修改 server.port 設定——不要直接改 package.json 的 script，那樣只是繞過問題而不是解決問題。

8. 清單類型

有序清單 — 部署步驟

1. 確認 npm run build 無錯誤
2. 執行 wrangler pages deploy dist/ 上傳產出物
3. 在 CF Dashboard 驗證 deployment 狀態為 Success

無序清單（含巢狀）

• 前端框架
  • Astro 5（靜態優先）
  • Tailwind CSS 4（樣式）
  • MDX（進階 Markdown）
• 部署平台
  • Cloudflare Pages（主站）
  • GitHub Actions（CI/CD）
• 內容工具
  • Obsidian（寫作環境）
  • git（版本控制）

任務清單

• 建立 Astro 專案基礎架構
• 設定 Obsidian wikilink 解析
• 完成 SuperPortia 主題色彩系統
• 上線 Blog 側邊欄（graph + search + categories）
• 實作 Email push 訂閱功能
• 建立 Daily Cycle 自動發文流程
• 串接 Drive SSoT 圖片來源

9. 引用

Obsidian + Astro 的組合正是這個哲學的實踐：作者在熟悉的 Vault 環境裡寫作，系統在背後處理所有技術細節。

10. 圖片與 Gallery

Gallery 自動偵測

當文章中有 2 至 6 張連續圖片時，Astro Modular 會自動將其渲染為 Gallery 格式：

• 2 張：並排兩欄
• 3 張：三欄或 2+1 配置
• 4–6 張：網格排列

超過 6 張連續圖片會恢復為單張行內顯示。在圖片之間插入任何非圖片內容（如文字或空行），即可打斷 gallery 偵測。

11. 嵌入類型

Astro Modular 支援以下外部資源嵌入：

12. 元件選擇指南

不確定該用哪個元件？參考這張決策表：

結語：模組統計

這篇文章本身就是一份完整展示。以下是 Agentic Blog 可用的內文模組總覽：