提示框、代码块与图表示例

最后更新于： 2026年9月11日 / 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/) — 面向静态站点的本地搜索库。

渲染效果： 正文末尾会出现带序号的上标跳转标记¹，点击平滑跳转到页面底部的脚注列表。

灵活运用提示框、代码标注和示意图，可以大幅提升技术文档的阅读舒适度与专业感。完整的语法约定请阅读 渲染规则详解。