📝 Markdown 樣式指南

這篇文章演示了 Astro-Theme-Aither 支援的每一個 Markdown 功能。寫作時可以將它作為參考。

標題

使用 ## 作為章節標題，### 作為子章節，#### 作為三級子章節。避免在正文中使用 #——文章標題已經作為頂級標題呈現。

三級標題

四級標題

標題的最佳實踐

一篇結構良好的文章通常只需要兩到三個層級的標題。過多的層級嵌套會讓讀者迷失方向。建議遵循以下原則：

• ## 用於主要章節：每個主要章節代表文章的一個核心論點或主題
• ### 用於子章節：在需要進一步細分時使用
• #### 謹慎使用：只在確實需要第三層級時才使用，通常表示你的內容結構可能需要重新組織

段落與換行

普通段落文字自然流動。在段落之間留一個空行來分隔它們。

這是第二個段落。保持每個段落圍繞一個想法，以獲得最佳閱讀體驗。

寫作時，建議每個段落控制在三到五句話之間。過長的段落會形成視覺上的「文字牆」，讓讀者望而卻步。適當地將長段落拆分成幾個短段落，可以顯著提升閱讀體驗。如果你發現一個段落超過了六七行，考慮將其拆分。

強調

• 粗體文字 使用 **雙星號**
• 斜體文字 使用 *單星號*
• 粗斜體 使用 ***三星號***
• 刪除線 使用 ~~雙波浪號~~

強調標記應謹慎使用。如果一段文字中到處都是粗體，那粗體就失去了強調的效果。一般來說，每個段落中最多使用一到兩處粗體來突出關鍵概念即可。斜體在中文排版中不太常用，因為中文字型的斜體渲染效果通常不如西文字型理想。

連結

行內連結 使用 [文字](url) 語法。

連結文字應該具有描述性，讓讀者不需要點擊就能知道連結指向的內容。避免使用「點擊這裡」或「連結」這樣的空洞文字。例如：

• 不佳：更多資訊請點擊這裡
• 推薦：查看 Astro 官方文件 了解更多

列表

無序列表：

• 第一項
• 第二項
  • 巢狀項
  • 另一個巢狀項
• 第三項

有序列表：

1. 第一步
2. 第二步
   1. 子步驟一
   2. 子步驟二
3. 第三步

任務列表：

• 搭建專案
• 寫第一篇文章
• 部署到生產環境

列表使用建議

列表是組織資訊的利器，但需要注意以下幾點：

• 當項目之間有明確的順序關係時，使用有序列表
• 當項目之間是並列關係時，使用無序列表
• 每個列表項盡量保持簡潔，通常一到兩行即可
• 如果列表項需要大量解釋，可能更適合使用子標題加段落的形式

引用

抽象的目的不是為了模糊，而是為了創造一個新的語意層級，在其中可以做到絕對精確。

— Edsger W. Dijkstra

巢狀引用：

第一層

第二層

第三層

引用區塊適合用於展示名人語錄、重要聲明或需要特別突出的文字段落。在技術文章中，也可以用來標記重要的警告或提示資訊。

程式碼

使用反引號包裹行內 程式碼。

帶語法高亮的程式碼區塊：

1
interface Post {
2
  title: string;
3
  date: Date;
4
  description?: string;
5
  tags?: string[];
6
  draft?: boolean;
7
}
8

9
function getPublishedPosts(posts: Post[]): Post[] {
10
  return posts
11
    .filter((post) => !post.draft)
12
    .sort((a, b) => b.date.getTime() - a.date.getTime());
13
}

1
@theme {
2
  --font-sans: 'system-ui', sans-serif;
3
  --font-serif: 'ui-serif', 'Georgia', serif;
4
}

程式碼區塊現在預設會顯示行號，寫教學、做程式碼審閱，或引用較長範例時都更順手。

程式碼區塊的技巧

撰寫包含程式碼的技術文章時，以下技巧能讓你的文章更具可讀性：

• 標註語言：在開啟的三個反引號後指定語言（如 typescript、css、python），啟用語法高亮
• 精簡範例：只展示與當前討論相關的程式碼，去掉無關的匯入和設定
• 加入註解：在關鍵行加上註解，幫助讀者理解程式碼意圖
• 前後文說明：在程式碼區塊之前說明這段程式碼要做什麼，之後解釋關鍵細節

1
# 使用列表推導式過濾並轉換資料
2
active_users = [
3
    user.name.upper()          # 將名字轉為大寫
4
    for user in all_users      # 遍歷所有使用者
5
    if user.is_active           # 只保留活躍使用者
6
]

數學公式

行內公式可以直接寫在句子裡，例如 $E = mc^2$；較大的公式則適合使用區塊形式：

這些公式會在建置階段透過 KaTeX 轉成靜態輸出，因此頁面不需要額外載入瀏覽器端數學引擎。

Mermaid 圖表

如果你要展示流程、順序或結構關係，可以使用 mermaid 程式碼區塊：

這類圖表會在 Astro 建置時直接轉成 SVG，不需要等到前端再執行 Mermaid。

心智圖

如果你想從 Markdown 層級直接生成真正的心智圖，可以使用 markmap 程式碼區塊：

它和一般圖表不同：Markmap 會保留內容層級，並提供輕量互動，適合整理綱要、課程內容或複雜主題。

表格

靠右對齊和置中欄位：

表格適合展示結構化的比較資訊。但需要注意，Markdown 表格在行動裝置上的展示可能不理想，因此建議表格的欄位數控制在四欄以內，並保持每個儲存格的內容簡短。

分隔線

使用 --- 建立分隔線：

分隔線後的內容。

分隔線適合用於在文章中標記主題的重大轉換。但不要過度使用——大多數時候，一個新的 ## 標題就足以表示章節的轉換。

圖片

圖片使用標準 Markdown 語法：

1
![替代文字](./image.jpg)

本主題以排版為核心，但在需要時圖片同樣可以正常使用。

圖片使用建議

• 始終提供替代文字：替代文字不僅有助於無障礙訪問，也是 SEO 的重要因素
• 最佳化圖片大小：在上傳前壓縮圖片，推薦使用 WebP 格式以獲得更好的壓縮率
• 有意義的圖片名稱：使用描述性的檔案名如 astro-project-structure.png，而非 screenshot-001.png

寫作風格總結

好的 Markdown 寫作不僅是正確使用語法，更是善用這些工具來組織和表達你的想法。記住以下原則：

1. 結構清晰：使用標題建立明確的層次結構
2. 段落精煉：每個段落聚焦一個概念
3. 善用列表：將並列資訊轉化為列表
4. 程式碼配文字：程式碼區塊前後都要有文字說明
5. 留白呼吸：適當的空白讓內容更易閱讀