用于轻量项目计划的 Mermaid 甘特图

当项目计划需要和实现说明放在同一个仓库里时，Mermaid 甘特图就很有用。文本源码可审阅、可版本化，因此适合发布计划、迁移计划和规模不大的文档项目。

明确日期和任务 ID

gantt
  title Documentation release
  dateFormat YYYY-MM-DD
  axisFormat %b %d

  section Research
  Audit existing pages :done, audit, 2026-07-11, 3d
  Select topics        :topics, after audit, 2d

  section Delivery
  Draft guides         :active, draft, after topics, 6d
  Technical review     :review, after draft, 2d
  Publish              :milestone, publish, after review, 0d

像 audit 和 draft 这样的任务 ID 可以稳定地作为依赖目标。人类可读的任务名可以改，而不会破坏 after 引用。在使用字面日期之前，先设置 dateFormat，这样读者和渲染器都能按同一种方式理解。

状态标记要少用

done、active、crit 和 milestone 这些标记可以强调状态，但如果每个任务都标成 critical，信号就失效了。里程碑没有持续时间，它表示决策点或交付点，而不是持续数天的工作。

把依赖关系当成沟通

after draft 表示图中的完成到开始依赖。真实排期可能还需要资源容量、并行工作比例、工作日历和部分完成度。Mermaid 不是完整的项目管理系统，所以不要让图表暗示它没有的精度。

如果周末和节假日会影响承诺，需要确认渲染环境是否支持排除日历，并在图旁边写清楚假设。对于合同级排期，应该以正式的计划系统为准，再附上一张简化的 Mermaid 视图。

让计划保持可审阅

把相关任务分组到不同 section，并保持标签简短。更新日期时，应该和实际承诺一起放进同一个 Pull Request。一个好看但日期过期的甘特图，不如一份朴素但最新的清单。

当图表超过一屏时，最好拆成路线图和详细计划。路线图展示阶段和里程碑，详细计划展示当前阶段的任务依赖。

在 本地 Mermaid 编辑器 中打开 Gantt 模板，验证源码后再导出为 SVG 或 PNG。