渲染規則詳解
本頁完整說明 EpoCanvas Docs 的渲染規則：一篇 Markdown 檔案經歷了哪些處理環節、每種語法會被渲染成什麼效果、哪些語法不被支援。寫文件前通讀一遍，可以避免絕大多數排版問題。
渲染管線：從 .md 檔案到線上頁面
圖：Markdown 渲染管線 5 步流程。各步驟在建置期按順序執行，建置產物為純靜態檔案，用戶端零執行時框架開銷。
一篇 Markdown 檔案從儲存到被讀者看到，經過以下五個環節：
- 內容收集：Astro 啟動或建置時掃描
src/content/docs/目錄，把每個.md/.mdx檔案登記為內容條目，並校驗 Frontmatter（缺少title會直接報錯）。 - Markdown 編譯：內文由 Markdown 編譯器（含 GFM 擴充）轉換為 HTML。表格、任務清單、刪除線等擴充語法在這一步生效。
- 程式碼區塊高亮：所有程式碼圍欄交給 Expressive Code 處理，產生帶語法高亮、標題欄、行號與複製按鈕的程式碼區塊。
- 套用網站佈局：編譯後的 HTML 被塞進 Starlight 的頁面骨架——頂欄、左側目錄、右側本頁目錄都由
src/components/starlight/下的客製化元件渲染。 - 產生索引與靜態檔案：
pnpm run build時 Pagefind 走訪所有產物頁面擷取全文索引；最終dist/目錄中的純 HTML 可直接託管到任何靜態伺服器。
Frontmatter 規則
title必填，缺失時建置報錯InvalidInputError；description建議填寫，會展示在搜尋引擎結果與分享卡片中；- Frontmatter 必須是檔案最開頭的合法 YAML 區塊，三個橫線缺一不可。
標題規則
| 規則 | 說明 |
|---|---|
內文不要寫一級標題 # | Frontmatter 的 title 已渲染為頁面大標題，內文再寫 # 會出現兩個大標題 |
二級標題 ## 開始內文 | ## 與 ### 自動進入右側「本頁目錄」 |
#### 及以下不進目錄 | 更深層級僅作內文樣式渲染 |
| 標題文字會產生錨點 | 中文標題的錨點即中文文字本身，如 #標題規則 |
提示框規則 (Asides)
提示框使用 Starlight 的三冒號語法，支援 4 種類型：
:::note補充說明類的提示。:::
:::tip提高效率的小技巧。:::
:::caution需要注意的風險或容易出錯的操作。:::
:::danger涉及資料遺失或不可逆操作的高風險提醒。:::還可以在類型後加自訂標題：:::tip[安裝提速]。
圖：四種提示框按上述語法書寫後的實際顯示效果，截取自提示框、程式碼區塊與圖表範例頁。
程式碼區塊規則
程式碼圍欄（三個反引號）由 Expressive Code 渲染，支援以下標註（寫在首行反引號後）：
| 標註寫法 | 作用 | 範例 |
|---|---|---|
| 語言標示 | 決定語法高亮方案 | ```ts |
title="..." | 顯示檔案名標題欄 | ```ts title=“src/config/site.ts” |
{2} / {2-4} | 高亮指定行 | ```ts {2} |
lang="diff" 或 diff | 紅綠對比展示增刪行 | ```diff |
bash / sh 等終端語言 | 渲染為終端風格邊框 | ```bash |
所有程式碼區塊自動附帶一鍵複製按鈕；程式碼文字會被 Pagefind 收錄進搜尋索引，讀者可以直接搜到程式碼裡的關鍵字。
圖片規則
- 圖片統一放在
public/images/canvas/，用絕對路徑引用：； - 架構與流程示意圖用
.svg向量格式，介面截圖用壓縮後的.png； - 描述文字必須填寫，這是圖片載入失敗時的替代文字，也是無障礙存取的依據；
- 目前版本不內建 Mermaid 圖表渲染：
```mermaid圍欄只會按普通程式碼區塊顯示原始碼。需要流程圖時，先在 mermaid.live 等工具中匯出 SVG，再作為圖片插入。
連結規則
- 站內連結：使用完整路徑並以
/開頭結尾，如/canvas/deployment/。文件路徑改動後，舊路徑要在astro.config.mjs的redirects表登記跳轉； - 錨點連結：
/canvas/rendering/#程式碼區塊規則可以直接定位到本頁小節； - 外部連結：寫完整 URL 即可，內文中會以主題色呈現。
其他渲染行為
| 語法 | 渲染結果 |
|---|---|
**粗體**、*斜體*、~~刪除線~~ | 對應的文字樣式 |
行內程式碼 | 主題色等寬字體膠囊 |
| Ctrl+K 寫法 | 鍵帽樣式的按鍵標示 |
| GFM 表格 | 帶邊框與懸停高亮的資料表格 |
- [x] 任務清單 | 視覺化勾選框（停用狀態） |
[^名稱] 腳註 | 內文上標序號 + 頁面底部腳註列表，支援點擊往返跳轉 |
Markdown 引用區塊 > | 左側主題色垂直線 + 淺色底 |
分隔線 --- | 貫通內文區的細分割線 |