提示框、程式碼區塊與圖表範例

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

編寫高品質的技術文件，不僅需要清晰的文字，還需要醒目的重點提示、格式規整的程式碼範例和一目瞭然的示意圖。本頁所有範例都是實際生效的語法，你看到的效果就是渲染結果——本文本身就是一個活的範例頁。

1. 四種彩色提示框

提示框使用三冒號語法：:::類型 開頭、::: 結尾，中間寫內容。本站基於 Starlight，支援 note、tip、caution、danger 四種類型。

提示框內部可以繼續使用列表、程式碼區塊、表格等語法：

在程式碼圍欄首行標註 title="檔案路徑"，並用 {行號} 高亮重點行：

```typescript title="src/config/site.ts" {2}
export const siteConfig = {
  name: 'EpoCanvas Docs', // 這一行會被高亮背景強調
  version: '1.2.0',
};
```

渲染效果：

export const siteConfig = {
  name: 'EpoCanvas Docs',
  version: '1.2.0',
};

展示設定升級或程式碼重構時，用 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',
});

bash、sh、powershell 等終端語言會渲染為終端風格的深色邊框：

pnpm run build

目前版本不內建 Mermaid 等文字圖表渲染。直接書寫 ```mermaid 圍欄只會按普通程式碼區塊顯示原始碼，不會產生圖形。

建議的做法是：在 mermaid.live 等工具中編寫並匯出 SVG 向量圖，儲存到 public/images/canvas/ 後按圖片語法插入。本站的架構圖、語言切換流程圖都是這樣製作的：

系統架構示意圖

圖：以 SVG 圖片形式插入的架構示意圖，任意縮放不模糊。

如果確實需要讓 Mermaid 原始碼直接渲染成圖，需要在專案中引入額外的渲染外掛（如 rehype-mermaid），屬於二次開發範疇，請評估維護成本後再引入。

- [x] 支援語法高亮
- [x] 支援一鍵複製
- [ ] 內建 Mermaid 渲染（規劃中）

渲染為帶勾選狀態的列表項。

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

靜態索引由 Pagefind 在建置時產生[^pagefind]。

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

渲染效果： 內文結尾會出現帶序號的上標跳轉標記¹，點擊平滑跳轉到頁面底部的腳註列表。

靈活運用提示框、程式碼標註和示意圖，可以大幅提升技術文件的閱讀舒適度與專業感。完整的語法約定請閱讀 渲染規則詳解。