Markdown 撰寫與排版指南

最後更新於： 2026年9月14日 / EpoCanvas 官方工程與架構規範

在 EpoCanvas Docs 中新增或編輯文件非常輕鬆。所有內文內容都用標準 Markdown 語法撰寫，只要會寫 Markdown，就能立即參與文件的撰寫和維護。

本頁是全站格式支援的完整清單：第 3 節逐條列出基礎 Markdown 格式，第 4 節列出本站額外支援的擴充語法。每一條都給出「怎麼寫」和「渲染出來長什麼樣」的對照，你現在看到的效果就是實際渲染結果。

1. 文件檔案放在哪裡？

所有文件檔案都存放在專案的 src/content/docs/ 目錄下：

src/content/docs/
├── index.mdx          # 網站的落地首頁
├── canvas/            # 核心文件章節（簡體中文，預設語言）
│   ├── index.md       # 產品簡介
│   ├── deployment.md  # 快速上手
│   ├── layout.md      # 頁面佈局
│   ├── ...            # 其他文件
└── en/ ja/ ...        # 其他 9 種語言的譯文，目錄結構與中文版完全對應

檔名要求：使用小寫英文字母和中劃線（例如 quickstart-guide.md），不要包含中文或空格。檔名決定存取路徑：canvas/deployment.md 對應 /canvas/deployment/。
副檔名：通常使用純文字的 .md 檔案即可；如果需要在文章中引入互動元件（如首頁的卡片網格），使用 .mdx 格式。
登記側邊欄：新建檔案後，需要在 astro.config.mjs 的 sidebar 陣列中登記，否則不會出現在左側目錄裡。
多語言譯文：其他語言的譯文放在 src/content/docs/<語言>/ 目錄下，子目錄結構與中文版一致（如 en/canvas/deployment.md 對應英文版快速上手）；尚未提供譯文的頁面會自動回退顯示中文。

2. 頭部中繼資料 (Frontmatter) 怎麼寫？

每一篇 Markdown 文件的最上方，都必須包含用三個橫線 --- 包裹的 YAML 中繼資料區塊：

---
title: 快速上手 (3 分鐘執行)
description: EpoCanvas Docs 本機環境準備、安裝相依套件與啟動服務指南。
---

欄位說明

欄位名稱	是否必填	作用說明
`title`	必填	文章主標題。渲染為頁面頂部的大標題，並作為瀏覽器分頁標題。
`description`	建議填寫	文章的簡短摘要。用於瀏覽器搜尋結果、社群平台分享卡片的描述文字。
`template`	僅首頁使用	設為 `splash` 時使用無側邊欄的落地頁模板。

3. 基礎 Markdown 格式全覽

本站使用帶 GFM 擴充的標準 Markdown 渲染，下面這些格式全部支援。先看總覽，再逐條看寫法與渲染效果對照：

格式	快速寫法	用途
標題	`## 小節標題`	組織章節結構，自動收錄進右側本頁目錄
段落與換行	空行分段	內文的基本單位
粗體 / 斜體 / 刪除線	`粗體` `斜體` `~~刪除線~~`	強調重點文字
行內程式碼	`命令`	標記指令、檔名、快捷鍵
鍵盤按鍵	`<kbd>Ctrl</kbd>`	鍵帽樣式的按鍵標示
無序 / 有序清單	`- 項目` / `1. 項目`	羅列並列或按步驟的內容
任務清單	`- [x] 已完成`	帶勾選框的核對清單
引用區塊	`> 引用文字`	引用原文、補充旁註
程式碼區塊	三個反引號包裹	多行程式碼，帶高亮和複製按鈕
表格	豎線分列	參數對照、資料羅列
連結	`[文字](地址)`	跳轉到站內其他頁或外部網站
圖片	`![描述](路徑)`	插入截圖、架構圖
分隔線	`---`	劃分大段落

3.1 標題層級

內文中不要寫一級標題（#）——Frontmatter 的 title 已經自動渲染為頁面大標題，內文再寫一個 # 會導致頁面出現兩個大標題。各級小節從二級標題（##）開始：

## 二級大標題（章節）

### 三級子標題（小節）

渲染效果：你正在讀的這一頁就是現成的例子——「3. 基礎 Markdown 格式全覽」是二級標題，本節「3.1 標題層級」是三級標題，兩者都已出現在右側「本頁目錄」裡。四級標題（####）只做內文樣式，不再進目錄，適合目錄不想收錄的細碎小節。

3.2 段落與換行

Markdown 用空行分段，這是新手最容易踩雷的地方：

這是第一段，兩句話之間只按了一次 Enter，
所以渲染後仍在同一個段落裡。

這一行與上文隔了一個空行，渲染後會分成新的段落。

這一行末尾有一個反斜線\
所以它下面這行會真的另起一行。

渲染效果：

這是第一段，兩句話之間只按了一次 Enter，所以渲染後仍在同一個段落裡。

這一行與上文隔了一個空行，渲染後會分成新的段落。

這一行末尾有一個反斜線
所以它下面這行會真的另起一行。

規則總結：單個 Enter = 同一段內換源碼不分段；想新起一段就空一行；想在段內強制換行，用行尾反斜線或行尾兩個空格。

3.3 文字強調與行內樣式

這是**粗體**，這是*斜體*，這是***粗斜體***，這是~~刪除線~~。

用行內程式碼標記指令與檔名：執行 `pnpm run dev` 開啟開發服務。

鍵盤按鍵用 HTML 標籤：<kbd>Ctrl</kbd> + <kbd>K</kbd> 開啟全站搜尋。

渲染效果：

這是粗體，這是斜體，這是粗斜體，這是~~刪除線~~。

用行內程式碼標記指令與檔名：執行 pnpm run dev 開啟開發服務。

鍵盤按鍵用 HTML 標籤：Ctrl + K 開啟全站搜尋。

3.4 清單與任務清單

無序清單，子項目縮排兩個空格：
- 核心功能一
- 核心功能二
  - 二的子功能
  - 二的另一個子功能

有序清單：
1. 第一步：安裝 Node.js
2. 第二步：Clone 程式碼儲存庫
3. 第三步：啟動開發服務

任務清單：
- [x] 支援語法高亮
- [x] 支援一鍵複製
- [ ] 待辦事項

渲染效果：

無序清單，子項目縮排兩個空格：

核心功能一
核心功能二
- 二的子功能
- 二的另一個子功能

有序清單：

第一步：安裝 Node.js
第二步：Clone 程式碼儲存庫
第三步：啟動開發服務

任務清單：

支援語法高亮
支援一鍵複製
待辦事項

3.5 引用區塊

> 這是一段引用。適合放原文摘錄、背景說明或旁註。
> 連續多行寫在同一個引用區塊裡。

> > 引用裡還可以再嵌套引用。

> 引用裡同樣能放清單：
>
> - 第一條
> - 第二條

渲染效果：

這是一段引用。適合放原文摘錄、背景說明或旁註。連續多行寫在同一個引用區塊裡。

引用裡還可以再嵌套引用。

引用裡同樣能放清單：

第一條

第二條

3.6 程式碼區塊

用三個反引號包裹，並在首行反引號後標註語言，即可獲得語法高亮；每個程式碼區塊右側自帶一鍵複製按鈕：

```js
export function formatBytes(bytes) {
  return `${(bytes / 1024).toFixed(1)} KB`;
}
```

渲染效果：

export function formatBytes(bytes) {
  return `${(bytes / 1024).toFixed(1)} KB`;
}

語言標示決定高亮方案，常用的 js、ts、bash、json、yaml、html、css、python 等都支援。bash 等終端語言會渲染成終端風格的深色邊框：

pnpm run build

程式碼區塊的檔名標題、指定行高亮等進階用法見第 4.2 節。

3.7 表格

表頭下方的橫線裡用冒號控制對齊方式（冒號在左為左對齊、兩邊都有為置中、在右為右對齊）：

| 指令 | 參數 | 說明 |
| :--- | :---: | ---: |
| `astro dev` | `--host` | 左對齊範例 |
| `astro build` | 無 | 置中範例 |
| `astro preview` | `--port` | 右對齊範例 |

渲染效果：

指令	參數	說明
`astro dev`	`--host`	左對齊範例
`astro build`	無	置中範例
`astro preview`	`--port`	右對齊範例

3.8 連結

站內連結：[快速上手](/canvas/deployment/)

外部連結：[Astro 官網](https://astro.build)

本頁錨點：[跳到「表格」一節](#37-表格)

自動連結：<https://github.com/shijianus/epocanvas-docs>

渲染效果：

站內連結：快速上手

外部連結：Astro 官網

本頁錨點：跳到「表格」一節

自動連結：https://github.com/shijianus/epocanvas-docs

寫法約定：

站內連結用完整路徑並以 / 開頭結尾（如 /canvas/deployment/），不要寫相對路徑；
錨點就是標題文字轉換後的 ID，中文標題的錨點即中文本身（去掉標點、空格換成短橫線），點擊瀏覽器網址列裡的地址即可複製帶錨點的連結；
連結文字要寫清楚目的地，不要寫「點這裡」。

3.9 圖片與圖註

把文件所需的圖片資產統一放在 public/images/canvas/ 目錄下，引用時使用以 / 開頭的絕對路徑：

![快速上手頁面在本機開發伺服器中的實際渲染效果](/images/canvas/ui-quickstart.png)

*圖：緊貼圖片下一行的斜體文字會作為圖註顯示。*

渲染效果：

快速上手頁面在本機開發伺服器中的實際渲染效果

圖：快速上手頁面的實際渲染效果，此處僅作示範。

圖片規範：

架構圖與流程圖：保存為 .svg 向量圖，在手機和高解析度螢幕上放大不模糊。本站的架構圖都在 public/images/canvas/docs-*.svg。
介面截圖：保存為壓縮過的 .png，寬度 1440 像素左右即可，不要直接上傳幾十 MB 的原圖。
描述文字必填：![ ] 裡的文字會渲染為圖片的替代文字，請認真描述圖片內容，不要留空。

圖片插入後務必在瀏覽器裡實際查看渲染效果，確認路徑正確、圖片顯示正常再提交。

3.10 分隔線

三個及以上短橫線獨佔一行渲染為分隔線，用於劃分大段落：

上面的內容講完了。

---

下面開始新的主題。

渲染效果：

上面的內容講完了。

下面開始新的主題。

4. 擴充格式：本站增強語法

以下格式是本站在標準 Markdown 之上額外支援的擴充語法，由渲染引擎（Starlight 提示框與 Expressive Code）提供。

4.1 四種彩色提示框

提示框用三冒號語法：:::類型 開頭、單獨一行 ::: 結尾，共四種類型，顏色和圖示各不相同：

在類型後加方括號可以自訂標題：

:::tip[安裝提速]
使用 pnpm 安裝相依套件比 npm 快得多：

```bash
npm install -g pnpm
```
:::

渲染效果：

提示框內部可以繼續使用清單、程式碼區塊、表格等任意排版，更多範例見提示框、程式碼區塊與圖表範例。

4.2 程式碼區塊檔名標題與行高亮

在程式碼圍欄首行標註 title="檔案路徑" 顯示標題欄，用 {行號} 高亮重點行，多個行號用逗號分隔：

```typescript title="src/config/site.ts" {2,4}
export const siteConfig = {
  name: 'EpoCanvas Docs', // ← 高亮行
  version: '1.0.0',
  locale: 'zh-CN',        // ← 高亮行
};
```

渲染效果：

export const siteConfig = {
  name: 'EpoCanvas Docs',
  version: '1.0.0',
  locale: 'zh-CN',
};

4.3 diff 增量對比

用 diff 語言展示設定改動，- 開頭的行顯示為刪除、+ 開頭的行顯示為新增：

```diff
  export default defineConfig({
-   site: 'http://localhost:3000',
+   site: 'https://docs.epocanvas.com',
  });
```

渲染效果：

export default defineConfig({
  site: 'http://localhost:3000',
  site: 'https://docs.epocanvas.com',
});

4.4 腳註

需要標註資料來源或補充說明時，用 GFM 腳註語法：

全站搜尋索引由 Pagefind 在建置時產生[^pf]。

[^pf]: [Pagefind 官方文件](https://pagefind.app/) — 面向靜態站點的本機搜尋庫。

渲染效果： 內文中會出現一個帶序號的上標跳轉標記¹，點擊平滑跳轉到頁面底部對應的腳註條目。

4.5 不支援與易錯寫法速查

下面這些寫法在別的平台常見，但在本站不生效或表現不符預期，寫文件時請直接避開：

易錯寫法	實際表現	正確替代
```mermaid 圍欄	按普通程式碼區塊顯示原始碼，不產生圖形	在 mermaid.live 匯出 SVG 後按圖片插入
`> [!NOTE]` GitHub 告示語法	渲染成普通引用區塊	改寫為 `:::note`
`:::warning` / `:::important`	靜默渲染成普通段落，沒有提示框樣式	改寫為 `:::caution`
內文寫一級標題 `#`	頁面出現兩個大標題	刪掉 `#`，內文從 `##` 開始
單個 Enter 想換行	兩行合併成一行	空行分段，或行尾加反斜線

5. 更進一步

想了解 Markdown 從檔案到頁面的完整渲染管線與全部約定？請閱讀 渲染規則詳解。
想看提示框、程式碼區塊、腳註等語法在一個「活的範例頁」裡的集中展示？請閱讀 提示框、程式碼區塊與圖表範例。

這就是本頁底部渲染出來的腳註本體——腳註內容無論寫在文中的哪個位置，都會統一收攏到頁面最底部。 ↩

Markdown 撰寫與排版指南

1. 文件檔案放在哪裡？

2. 頭部中繼資料 (Frontmatter) 怎麼寫？

欄位說明

3. 基礎 Markdown 格式全覽

3.1 標題層級

3.2 段落與換行

3.3 文字強調與行內樣式

3.4 清單與任務清單

3.5 引用區塊

3.6 程式碼區塊

3.7 表格

3.8 連結

3.9 圖片與圖註

3.10 分隔線

4. 擴充格式：本站增強語法

4.1 四種彩色提示框

4.2 程式碼區塊檔名標題與行高亮

4.3 diff 增量對比

4.4 腳註

4.5 不支援與易錯寫法速查

5. 更進一步

註腳