📝 Markdown 樣式指南

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

標題

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

三級標題

四級標題

標題的最佳實踐

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

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

段落與換行

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

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

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

強調

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

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

連結

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

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

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

列表

無序列表：

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

有序列表：

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

任務列表：

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

列表使用建議

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

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

引用

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

— Edsger W. Dijkstra

巢狀引用：

第一層

第二層

第三層

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

程式碼

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

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

interface Post {
  title: string;
  date: Date;
  description?: string;
  tags?: string[];
  draft?: boolean;
}

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

@theme {
  --font-sans: 'system-ui', sans-serif;
  --font-serif: 'ui-serif', 'Georgia', serif;
}

程式碼區塊的技巧

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

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

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

表格

功能	狀態	備註
深色模式	支援	淺色 / 深色 / 跟隨系統
RSS 訂閱	內建	`/rss.xml`
網站地圖	自動產生	透過 `@astrojs/sitemap`
SEO	內建	Open Graph + 規範連結

靠右對齊和置中欄位：

靠左	置中	靠右
文字	文字	文字
較長文字	較長文字	較長文字

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

分隔線

使用 --- 建立分隔線：

分隔線後的內容。

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

圖片

圖片使用標準 Markdown 語法：

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

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

圖片使用建議

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

寫作風格總結

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

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