If you've ever needed to map out a project timeline in code without opening a heavy project management tool Mermaid's Gantt chart syntax is one of the fastest ways to do it. It lets you define tasks, durations, dependencies, and milestones using plain text that renders into a visual chart. Whether you're documenting a sprint in a README, planning a product roadmap in a wiki, or illustrating phases in a presentation, understanding the syntax saves real time and reduces miscommunication across teams.

What Exactly Is a Mermaid Gantt Chart?

A Mermaid Gantt chart is a project timeline diagram written in Mermaid diagram syntax a Markdown-like language that converts text into visual diagrams. You define tasks, their start dates or durations, and optional dependencies. Mermaid's JavaScript library then renders this into an SVG Gantt chart that works in GitHub, GitLab, Notion, Obsidian, and many other platforms that support Mermaid rendering.

Unlike drawing tools where you drag and drop boxes, the entire chart lives as readable text. That means your project timeline is version-controlled, diffable, and easy to update without a mouse.

How Do You Write a Basic Mermaid Gantt Chart?

Every Mermaid Gantt chart starts with the gantt keyword, followed by a title, date format, and then one or more sections containing tasks. Here's the simplest working example:

gantt
 title Project Alpha
 dateFormat YYYY-MM-DD
 section Planning
 Research :a1, 2024-01-01, 14d
 Requirements Doc :a2, after a1, 7d
 section Development
 Build Backend :b1, after a2, 21d
 Build Frontend :b2, after a2, 28d
 section Testing
 QA Testing :c1, after b1, 10d

This produces a chart with three sections, five tasks, and dependencies between them. The after a1 syntax tells Mermaid to start a task once another finishes.

What Are the Key Syntax Elements You Need to Know?

Chart Header Directives

These lines appear once at the top, before any sections or tasks:

  • gantt Required. Tells Mermaid to render a Gantt chart.
  • title Sets the chart's title text.
  • dateFormat Defines how dates are written. Common values: YYYY-MM-DD, DD-MM-YYYY, YYYYMMDD.
  • axisFormat Controls how dates display on the timeline axis. Example: %Y-%m-%d.
  • tickInterval Sets the spacing of tick marks on the axis. Example: 1week, 1month.
  • excludes Skips specific days. Use weekends to exclude Saturday and Sunday.
  • todayMarker Highlights the current date. Set to stroke-width:3px,stroke:#00ff00,opacity:0.8 for visibility.

Sections

A section line groups related tasks under a label. You can have as many sections as you need. They act as visual categories like "Planning," "Development," or "Deployment."

Task Syntax

Each task follows this pattern:

Task Label :[task-id], [start], [duration or end]
  • Task Label The visible name of the task.
  • task-id A unique identifier (like a1, task-2, or dev_phase). Used for dependencies.
  • Start Either an absolute date (2024-03-01) or a reference (after a1).
  • Duration Written as a number plus unit: 5d (days), 2w (weeks), 1m (months). You can also set an explicit end date instead.

Task Status Keywords

You can mark a task's status by adding a keyword after the task definition:

  • done Marks the task as completed (renders with a fill).
  • active Marks the task as currently in progress (animated or highlighted).
  • crit Marks the task as critical (renders in red).

You can combine them: crit, active or crit, done.

section Deployment
 Server Setup :crit, done, d1, 2024-06-01, 3d
 Launch :crit, active, d2, after d1, 2d

Dependencies

Dependencies tell Mermaid that one task starts after another finishes. Use the keyword after followed by one or more task IDs:

Design Review :dr1, after a1 a2, 3d

This means "Design Review" starts after both a1 and a2 are done. For multiple dependencies, list the IDs separated by spaces.

How Do You Set Milestones in a Mermaid Gantt Chart?

Milestones represent single events a deadline, a release date, a review meeting with zero duration. In Mermaid, you mark a task as a milestone by setting its duration to 0d:

section Launch
 Code Freeze :cf, 2024-08-01, 0d
 Product Launch :pl, 2024-08-15, 0d

Milestones render as diamond shapes on the timeline, making them easy to spot.

What Does a Full Practical Example Look Like?

Here's a realistic project plan combining all the elements above:

gantt
 title Website Redesign Project
 dateFormat YYYY-MM-DD
 excludes weekends
 tickInterval 1week
 todayMarker stroke-width:2px,stroke:#f00,opacity:0.8

 section Discovery
 Stakeholder Interviews :a1, 2024-02-05, 5d
 User Research :a2, 2024-02-12, 10d
 Findings Report :a3, after a2, 3d

 section Design
 Wireframes :b1, after a3, 7d
 Visual Mockups :b2, after b1, 10d
 Design Review :crit, b3, after b2, 2d

 section Development
 CMS Setup :c1, after b3, 5d
 Frontend Build :c2, after c1, 15d
 API Integration :c3, after c1, 12d

 section Testing & Launch
 QA :d1, after c2 c3, 8d
 Bug Fixes :d2, after d1, 5d
 Launch :crit, milestone, d3, after d2, 0d

This chart tracks a multi-phase website redesign, excludes weekends, marks critical tasks, and includes a launch milestone. You can paste this directly into any Mermaid-compatible editor to see the rendered timeline.

Common Mistakes When Writing Mermaid Gantt Charts

  1. Missing the dateFormat directive. Without it, Mermaid defaults to a format that may not match your dates, causing parsing errors or wrong timelines.
  2. Using inconsistent date formats. If you set dateFormat YYYY-MM-DD, every date in the chart must follow that format. Mixing formats breaks rendering.
  3. Forgetting indentation. Section names and tasks must be indented consistently. Mermaid is somewhat forgiving, but irregular indentation can cause unexpected behavior.
  4. Duplicate task IDs. Each task ID must be unique. Reusing an ID like a1 in two places causes dependency errors.
  5. Referencing nonexistent task IDs in dependencies. If you write after x5 but x5 doesn't exist, Mermaid either ignores the dependency or renders incorrectly.
  6. Not quoting task labels with special characters. If your task name contains a colon, parenthesis, or other special character, wrap it in quotes to avoid parsing issues.
  7. Confusing duration units. d is days, w is weeks, m is months. Using capital letters or writing out "days" doesn't work.

Useful Tips for Working With Mermaid Gantt Syntax

  • Use excludes weekends to make your timeline reflect actual working days. Without it, the chart counts every calendar day.
  • Add todayMarker when sharing charts in wikis or dashboards so viewers immediately see where "today" falls on the timeline.
  • Name your task IDs descriptively. Instead of a1, a2, a3, use research, wireframes, review. It makes dependencies much easier to read and maintain.
  • Use crit sparingly. If everything is critical, nothing is. Reserve it for tasks that directly block the launch or have hard deadlines.
  • Test small charts first. If you're building a complex timeline, start with two or three tasks, confirm they render correctly, then expand. Debugging a 40-task chart from scratch is frustrating.
  • Render preview often. Use the Mermaid Live Editor to check your chart as you write. It shows errors in real time and lets you export SVG or PNG files.

Where Can You Use Mermaid Gantt Charts?

Mermaid Gantt charts work anywhere the Mermaid library is supported or embedded. Common places include:

  • GitHub and GitLab READMEs and Markdown files
  • Notion pages (via Mermaid code blocks)
  • Obsidian notes
  • Confluence (with Mermaid plugins)
  • Jupyter Notebooks
  • Static site generators like Hugo, Docusaurus, or MkDocs
  • HTML pages using the Mermaid.js CDN script

If you're already using Mermaid for other diagram types like flowcharts or sequence diagrams, you can read more about Mermaid flowchart code examples and sequence diagram syntax to round out your diagramming toolkit.

How Does Mermaid Gantt Compare to Other Project Timeline Tools?

Mermaid Gantt charts are text-based, which is both their strength and their limitation. They're ideal for small-to-medium projects where you want timelines stored alongside code or documentation. They don't support resource allocation, cost tracking, or complex task splitting the way Microsoft Project or Jira Gantt plugins do. But for planning sprints, illustrating phases in documentation, or sharing a quick project overview in a pull request, they're faster and more portable than any visual tool.

Quick Reference Checklist Before You Publish Your Chart

Before sharing your Mermaid Gantt chart, run through this checklist:

  • ✅ gantt keyword is on the first line
  • ✅ dateFormat is declared and matches all dates in the chart
  • ✅ Every task has a unique ID
  • ✅ All after references point to existing task IDs
  • ✅ Sections are properly indented
  • ✅ Duration uses valid units (d, w, m)
  • ✅ Special characters in task labels are quoted
  • ✅ Chart has been previewed in the Mermaid Live Editor
  • ✅ excludes weekends is added if you want working-day-only timelines
  • ✅ Critical tasks and milestones are visually distinct

Save this checklist and paste it into your next pull request or project planning doc. It takes 30 seconds to review and catches the most common rendering issues before anyone else sees the chart. For more Mermaid syntax references, check out the full Mermaid syntax cheat sheet to keep all diagram types at your fingertips.