渲染规则详解
本页完整说明 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 引用块 > | 左侧主题色竖线 + 浅色底 |
分隔线 --- | 贯通正文区的细分割线 |