Mermaid 时间线语法：8 个可直接复制的示例 · 2026

Mermaid 时间线语法很短：先写 timeline，按需加入标题和分组，然后用“时间段 : 事件”逐行填写。产品发布历史、项目里程碑、研究阶段和事故处理记录，都可以直接放进 Markdown 文档里维护。

真正容易卡住的不是前三行，而是同一时间段怎么放多个事件、怎样分阶段、长文案如何换行、横向和竖向怎么切换，以及什么时候根本不该用 Timeline。下面 8 个示例从最小可运行代码开始，逐步加到一份完整的发布计划。

Mermaid 官方目前仍把 Timeline 标为实验性图表。基础语法已经稳定，但较新的功能可能取决于实际渲染环境中的 Mermaid 版本。高级写法上线前，要在最终发布平台里再渲染一次。

Mermaid 时间线语法速查

基础结构如下：

timeline
    title 可选标题
    时间段 : 事件
    时间段 : 事件 : 另一个事件

先记住三件事：

• timeline 用来声明图表类型，必须写在时间线内容之前。
• 第一个冒号左边是时间段，可以写年份、日期、季度、Sprint 名称，也可以写一个描述性阶段。
• 冒号右边是事件；同一个时间段可以挂多个事件。

Mermaid 按代码中的顺序摆放时间段，不会把 2025、2026 Q1 或“第 4 周”解析成带比例的日期坐标。比如依次写 2020、2025、2026，顺序没有问题，但五年的间隔不会自动画成一年的五倍。

所以 Timeline 最适合讲先后顺序。如果你真正关心任务时长和依赖关系，可以先跳到时间线和甘特图区别，再决定要不要继续写。

示例 1：最小可运行的 Mermaid 时间线

先用三个时间段、每段一个事件测试环境：

timeline
    title 文档迁移计划
    第 1 周 : 盘点现有页面
    第 2 周 : 转换核心指南
    第 3 周 : 发布并检查链接

渲染结果为空时，这一版最适合排错。它能正常显示，再一次只加入一个能力：分组、多个事件或配置。这样能迅速判断是基础语法有问题，还是版本不支持某个新功能。

时间段不一定非要写日期。Sprint 名称、发布阶段和历史时期都可以，因为 Mermaid 把它当成展示文字，而不是拿来做日期运算。

示例 2：同一时间段添加多个事件

一个发布季度经常有多个关键事件。时间段只写一次，后面继续用冒号添加：

timeline
    title 产品发布时间线
    2026 Q1 : 设计系统评审通过 : API 契约冻结
    2026 Q2 : 开放内测 : 无障碍评审 : 合作方测试
    2026 Q3 : 正式上线 : 移动端发布

内容较长时，把后续事件拆成缩进的新行：

timeline
    title 产品发布时间线
    2026 Q1 : 设计系统评审通过
            : API 契约冻结
    2026 Q2 : 开放内测
            : 无障碍评审
            : 合作方测试

两种写法表达的是同一种关系：多个事件归属于同一时间段。多行版更适合放进 Git，新增事件只改一行，不必重写整条长句。

事件的粒度要一致。“Q2 开放内测”和“把按钮换成蓝色”放在一起，即使语法正确，信息层级也会很乱。发布型时间线保留决策和里程碑就够了，不要把全部待办事项搬进来。

示例 3：用 section 按阶段分组

读者需要先扫阶段、再看事件时，用 section：

timeline
    title 客户门户发布计划
    section 调研
        1 月 : 客户访谈 : 客服工单分析
        2 月 : 需求评审通过
    section 交付
        3 月 : 开始开发
        4 月 : 内部演示 : 安全评审
    section 发布
        5 月 : 客户内测
        6 月 : 正式开放

一个时间段会归入它前面最近的 section，直到代码中出现下一个分组。产品阶段、公司发展时期、学期和事故处理阶段都适合这样整理。

不要给每个时间段都套一个 section，否则刚建立的层级又被抹平了。一张需要快速扫读的图，通常有三到五个真正有意义的分组就够。

示例 4：控制长文案换行

Mermaid 会自动折行，也可以用 <br> 指定更合适的断行位置：

timeline
    title 研究项目时间线
    第 1 月 : 回顾既有研究<br>并确定研究问题
    第 2 月 : 提交伦理审查
    第 3-4 月 : 招募参与者<br>并收集访谈资料
    第 5 月 : 编码访谈记录 : 复核主题
    第 6 月 : 撰写研究发现<br>并准备投稿

页面内容区较窄时，主动换行能让版面更稳定。但它不能代替编辑：如果每个事件都要写三行，说明时间线正在承担段落级信息。把节点缩短，详细解释放到图下方或正文里。

如果你需要精确控制节点位置，而不是交给自动布局，可以把相同里程碑放进可编辑时间线模板。白板更适合演示型排版；Mermaid 更适合把图保持成简洁文本。

示例 5：制作竖向 Mermaid 时间线

Mermaid 11.14.0 加入了从上到下的 TD 方向，写在声明行即可：

timeline TD
    title 故障处理记录
    09:05 : 监控告警触发
    09:12 : 值班工程师确认
    09:24 : 定位到异常发布
    09:31 : 开始回滚
    09:46 : 错误率恢复正常
    10:15 : 发布用户说明

timeline LR 是默认的从左到右布局。竖向时间线更适合窄栏文档，每个时间段的解释较长时也更容易读。只有五六个短里程碑时，横向布局通常更紧凑。

基础示例能显示、TD 却不工作，先检查 Markdown 平台或文档生成器内置的 Mermaid 版本。在线编辑器可能已经升级，但你正在使用的平台仍捆绑着较旧版本。

示例 6：设置主题和统一配色

在图表声明前加入 YAML frontmatter，可以选择主题并关闭默认的多色效果：

---
config:
  theme: base
  timeline:
    disableMulticolor: true
---
timeline
    title API 现代化计划
    阶段 1 : 盘点现有接口
    阶段 2 : 引入版本化契约
    阶段 3 : 迁移优先客户
    阶段 4 : 下线旧接口

如果不同 section 需要不同颜色，可以设置 cScale0 到 cScale11 以及对应文字颜色：

---
config:
  theme: base
  themeVariables:
    cScale0: '#dbe4ff'
    cScaleLabel0: '#1c2c5b'
    cScale1: '#d3f9d8'
    cScaleLabel1: '#14532d'
---
timeline
    title 服务迁移计划
    section 准备
        Sprint 1 : 盘点依赖
        Sprint 2 : 补齐可观测性
    section 迁移
        Sprint 3 : 切换内部流量
        Sprint 4 : 切换客户流量

配置要服务于信息。一张默认配色但文字清楚的时间线，比一张主题复杂、标签对比度不足的图更有用。

示例 7：在 Markdown 里嵌入 Mermaid 时间线

发布环境支持 Mermaid 时，把源代码放进语言标记为 mermaid 的 fenced code block：

```mermaid
timeline
    title 版本历史
    v1.0 : 首次发布
    v1.1 : 加入搜索
    v1.2 : 改进导出
```

页面只显示代码、没有生成图时，先确认平台是否启用了 Mermaid 渲染。语法正确并不代表所有 Markdown 渲染器都认识 Mermaid。自建文档站可能需要插件或构建步骤，应用内则需要按官方方式初始化 Mermaid 库。

可以像维护代码一样维护时间线：标签保持简短，在 Pull Request 中检查 diff，发布前通过 CI 或预览页渲染一次。缩进或 frontmatter 写错一处，在预览中发现总比文档上线后再排查省事。

如果团队还在决定要不要采用文本画图，可以先看 Mermaid 和 draw.io 对比，重点理解版本可追踪源码和手动视觉控制之间的取舍。

示例 8：Mermaid 时间线项目计划示例

这个 Mermaid 时间线项目计划示例同时使用标题、阶段、多里程碑和强制换行，但不会假装自己是任务排期工具：

timeline
    title 客户门户项目计划
    section 调研
        1 月 : 访谈客户
             : 确认需求
    section 交付
        2 月 : 原型评审通过
        3 月 : 核心流程开发完成
             : 通过安全评审
        4 月 : 试点客户开始使用
    section 上线
        5 月 : 正式开放
             : 完成客服交接

这里故意没有工程任务、精确工期、负责人和依赖箭头。这些信息应该留在详细执行排期中。这张时间线相当于项目计划的管理层视图：发生什么、顺序怎样、哪些里程碑值得相关方关注。

改成自己的版本时，先换标题，再给三个阶段改名，最后替换时间段和里程碑。需要在幻灯片或报告里放项目计划图片时，可以把 Mermaid 渲染结果导出为 SVG 或 PNG。如果源码已经超过一个屏幕，就应拆分时间线，或者把执行细节升级到甘特图。

Mermaid Timeline 和 Mermaid Gantt 怎么选

名字看起来很像，但两者回答的问题不同：

图是叙事，用 Timeline；图是执行计划，用 Gantt。在事件名称后面写“开发，六周”并不会让 Timeline 具备甘特图的排期能力。

如果需要任务条和依赖关系，可以直接使用甘特图模板，或参考免费甘特图工具对比。如果要做一张给人演示、可以自由移动节点的时间线，则使用可视化时间线模板。

Mermaid 时间线常见错误

页面只显示代码

Markdown 平台可能不支持 Mermaid，或者渲染能力被关闭了。先把相同代码放到支持 Mermaid 的预览环境，确认语法没问题，再调整平台配置。

加入配置后整张图消失

先暂时删掉 YAML frontmatter。基础时间线恢复后，再检查缩进、大小写以及开头和结尾的 ---。Mermaid 配置区分大小写，YAML 结构错误也可能阻止图表加载。

timeline TD 不工作

从上到下的布局需要 Mermaid 11.14.0 或更高版本。不能升级渲染器时，先使用默认的横向布局。

事件顺序不对

Mermaid 按源码顺序摆放。直接调整代码行的顺序，不要期待它自动按时间标签排序。

日期间距看起来一样

Timeline 传达的是顺序，不是按比例计算的时间坐标。重要的时间差要写进标签，或者换成能根据实际日期计算位置的图表。

内容太挤

缩短事件名称、用 section 归组、切换成 TD，或者把一段过长历史拆成两张图。如果手动控制位置比保持文本源码更重要，就应该使用可视化画布，而不是继续给代码塞布局要求。

维护 Mermaid 时间线的实用流程

先把时间段写成普通大纲，再加入 Mermaid 标点。删掉任务级细节，确定三到五个阶段，让每个事件都描述一个结果。之后转换成“时间段 : 事件”的基础形式并渲染。

高级能力一次只加一个：多事件、section、方向，最后才是主题配置。这样每次渲染失败，排查范围都很小。源码和它解释的文档放在一起；Mermaid 依赖或文档主题升级后，都重新看一次渲染结果。

Mermaid 最适合图和代码放在一起的场景。需要更完整的 UML 能力，可以看 Mermaid 和 PlantUML 对比；如果问题在自动布局而不是语法，Mermaid 替代工具对比了 D2、Graphviz、PlantUML 和可视化编辑器。

相关阅读

• Mermaid vs PlantUML vs D2——按 Markdown 支持、UML 深度和自动布局选择文本画图语言。
• Mermaid 替代工具——当自动布局或图表类型不够用时，对比文本和可视化方案。
• Mermaid 和 draw.io 对比——选择图表即代码还是拖拽编辑。
• Mermaid 和 PlantUML 对比——比较 Markdown 友好的轻量语法和更全面的 UML 能力。
• 免费时间线工具对比——比较可视化时间线工具和模板。
• 简单项目时间线教程——不加任务依赖，只做里程碑项目时间线。