Mermaid Gantt Charts for Lightweight Project Plans

Mermaid Gantt charts are useful when a project plan belongs in the same repository as its implementation notes. The text source is reviewable and versioned, making it suitable for release plans, migrations, and documentation projects with a limited number of tasks.

Define dates and task IDs explicitly

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

Task IDs such as audit and draft provide stable dependency targets. Human-readable task labels can change without breaking after references. Set dateFormat before using literal dates so readers and renderers interpret them consistently.

Use status markers sparingly

Markers such as done, active, crit, and milestone can highlight state, but a chart with every task marked critical loses the signal. A milestone has no duration and represents a decision or delivery point, not work that takes place over several days.

Treat dependencies as communication

after draft expresses a finish-to-start dependency in the diagram. Real project scheduling may also need resource capacity, parallel work percentages, working calendars, and partial completion. Mermaid is not a full project-management engine, so avoid implying precision the model does not contain.

If weekends and holidays affect a commitment, confirm how the rendering environment handles exclusion settings and document the calendar assumption next to the chart. For contractual schedules, use the authoritative planning system and embed or link a simplified Mermaid view.

Keep the plan reviewable

Group related tasks into sections and keep labels short. Update dates in the same pull request that changes the underlying commitment. A visually attractive Gantt chart with stale dates is less useful than a plain current checklist.

When the chart grows beyond one screen, split it into a roadmap and a detailed plan. The roadmap should show phases and milestones; the detailed plan can show task dependencies for the current phase.

Open the Gantt template in the local Mermaid editor to validate the source and export it as SVG or PNG.