Markdown 编写与排版指南

最后更新于： 2026年9月13日 / 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 用空行分段，这是新手最容易踩坑的地方：

这是第一段，两句话之间只按了一次回车，
所以渲染后仍在同一个段落里。

这一行与上文隔了一个空行，渲染后会分成新的段落。

这一行末尾有一个反斜杠\
所以它下面这行会真的另起一行。

渲染效果：

这是第一段，两句话之间只按了一次回车，所以渲染后仍在同一个段落里。

这一行与上文隔了一个空行，渲染后会分成新的段落。

这一行末尾有一个反斜杠
所以它下面这行会真的另起一行。

规则总结：单个回车 = 同一段内换源码不分段；想新起一段就空一行；想在段内强制换行，用行尾反斜杠或行尾两个空格。

3.3 文字强调与行内样式

这是**加粗**，这是*斜体*，这是***粗斜体***，这是~~删除线~~。

用行内代码标记命令与文件名：执行 `pnpm run dev` 打开开发服务。

键盘按键用 HTML 标签：<kbd>Ctrl</kbd> + <kbd>K</kbd> 打开全站搜索。

渲染效果：

这是加粗，这是斜体，这是粗斜体，这是~~删除线~~。

用行内代码标记命令与文件名：执行 pnpm run dev 打开开发服务。

键盘按键用 HTML 标签：Ctrl + K 打开全站搜索。

3.4 列表与任务清单

无序列表，子项缩进两个空格：
- 核心功能一
- 核心功能二
  - 二的子功能
  - 二的另一个子功能

有序列表：
1. 第一步：安装 Node.js
2. 第二步：克隆代码仓库
3. 第三步：启动开发服务

任务清单：
- [x] 支持语法高亮
- [x] 支持一键复制
- [ ] 待办事项

渲染效果：

无序列表，子项缩进两个空格：

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

有序列表：

第一步：安装 Node.js
第二步：克隆代码仓库
第三步：启动开发服务

任务清单：

支持语法高亮
支持一键复制
待办事项

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`
正文写一级标题 `#`	页面出现两个大标题	删掉 `#`，正文从 `##` 开始
单个回车想换行	两行合并成一行	空行分段，或行尾加反斜杠

5. 更进一步

想了解 Markdown 从文件到页面的完整渲染管线与全部约定？请阅读 渲染规则详解。
想看提示框、代码块、脚注等语法在一个”活的示例页”里的集中展示？请阅读 提示框、代码块与图表示例。

这就是本页底部渲染出来的脚注本体——脚注内容无论写在文中的哪个位置，都会统一收拢到页面最底部。 ↩