Mermaid Gantt Chart Scripting Reference and Best Practices Guide

If you've ever tried to visualize a project timeline using Mermaid's Gantt chart syntax, you know it can feel like learning a mini programming language. The good news? Once you understand the core commands and a few best practices, building readable, functional Gantt charts becomes second nature. This reference covers the full scripting syntax, common pitfalls, and real patterns that save you time when planning sprints, launches, or any project with a timeline.

What is a Mermaid Gantt chart, and why do people use it?

Mermaid is a JavaScript-based diagramming tool that renders text-based markup into visual diagrams. Its Gantt chart feature lets you define project schedules tasks, durations, dependencies, sections, and milestones using plain text code. Instead of dragging boxes in a GUI tool, you write a few lines of script and get a clean, shareable timeline.

Developers and project managers use Mermaid Gantt charts because the source is just text. That means you can version-control your timelines in Git, embed them in Markdown files, include them in pull requests, or render them in documentation sites. If you're already using Mermaid for other diagram types, adding Gantt charts to your toolkit is a natural step and if you're still getting comfortable with basic Mermaid diagram syntax, starting there first will make this much easier.

How do you write the basic syntax for a Mermaid Gantt chart?

Every Mermaid Gantt chart starts with the gantt keyword. Below that, you define a title, date format, axis format, and sections then list your tasks inside those sections.

Here's a minimal example:

gantt title Project Alpha Timeline dateFormat YYYY-MM-DD section Planning Research & discovery :a1, 2024-01-01, 10d Write PRD :a2, after a1, 5d section Development Backend work :b1, 2024-01-16, 14d Frontend work :b2, after a2, 12d Launch :milestone, m1, after b1, 0d

That renders a timeline with two sections, task dependencies, and a milestone. Let's break down each part.

Task syntax explained

The task line follows this pattern:

Task Name :taskId, startDate, duration

You can also use after taskId instead of a fixed date to create dependencies. Durations accept d (days), w (weeks), h (hours), and m (minutes). Milestones use a duration of 0d.

What are the core directives and attributes you need to know?

These are the top-level directives that configure your chart:

title – Sets the chart title displayed at the top.
dateFormat – Defines how dates are parsed. Common formats: YYYY-MM-DD, DD-MM-YYYY, YYYYMMDD.
axisFormat – Controls how dates appear on the timeline axis, for example %Y-%m-%d or %b %d.
tickInterval – Sets the spacing of axis ticks (e.g., 1day, 1week, 1month).
excludes – Skips specific days like weekends. Use excludes weekends or list specific dates.
todayMarker – Toggles the "today" line. Set to off to hide it.

Task status keywords

Mermaid supports these task states, which change the visual appearance:

done – Marks a task as completed. Example: Design :done, d1, 2024-01-01, 5d
active – Highlights a task as in-progress. Example: Build :active, b1, 2024-01-06, 10d
crit – Marks a task as critical (renders in red). Example: Deadline :crit, dl1, 2024-01-20, 3d

You can combine these: Build :active, crit, b1, 2024-01-06, 10d

How do you set up task dependencies correctly?

Dependencies are one of the most useful features. Instead of hardcoding every start date, you reference another task ID and use the after keyword.

section Testing Write unit tests :t1, after b1, 5d Integration tests :t2, after t1, 3d QA sign-off :milestone, after t2, 0d

This chains tasks so each one starts when the previous finishes. You can also chain from multiple tasks: Deploy :after t2, after b2, 2d the task starts after both t2 and b2 are done.

A common mistake is referencing a task ID that hasn't been defined yet. Mermaid won't always throw an obvious error it may just render incorrectly. Always double-check your IDs are spelled consistently and defined above where they're referenced.

What are the most common mistakes people make with Mermaid Gantt scripts?

1. Mixing date formats

If your dateFormat is set to YYYY-MM-DD but one task uses 01/15/2024, the chart will break or render dates incorrectly. Pick one format and stick with it throughout.

2. Forgetting the colon before the task ID

The syntax requires a colon after the task name: Task Name :id, .... Missing this colon is a silent error the line gets interpreted wrong, and your chart may render nothing or garble the output.

3. Not specifying sections

Without section declarations, your tasks all fall into a default group. This makes charts with many tasks hard to read. Group related tasks under clear section names.

4. Overloading a single chart

If your Gantt chart has 40+ tasks, it becomes hard to read in most renderers. Consider splitting into separate charts per phase or team. This is also easier to maintain in version control.

5. Using durations that don't match the date format

If your dateFormat doesn't include time but you use 2h durations, the chart may behave unexpectedly. Keep duration units consistent with your date precision.

How do you add milestones and mark critical deadlines?

Milestones are zero-duration tasks. They're great for marking launch dates, review points, or hard deadlines.

Release v1.0 :milestone, m1, 2024-03-01, 0d

For critical-path tasks, use the crit keyword. This renders the bar in red, drawing attention to tasks that directly affect your deadline.

Final review :crit, fr1, 2024-02-25, 3d

Combining milestones with critical tasks gives your chart a clear visual hierarchy that anyone can scan quickly.

What are some practical best practices for real projects?

After using Mermaid Gantt charts across dozens of projects, here are patterns that hold up:

Name task IDs with meaning. Use prefixes like plan_, dev_, test_ instead of a1, b2. When you come back in three months, dev_auth_flow tells you more than t7.
Use sections to mirror your team structure or phases. This makes the chart self-documenting.
Start with dependencies, not dates. Define your task chain with after references first, then pin a start date only on the first task. This way, if one task shifts, everything downstream adjusts.
Exclude weekends for work projects. Add excludes weekends after the dateFormat line. Without this, a 5-day task may appear to span a weekend.
Keep it under 30 tasks per chart. Beyond that, split into separate linked diagrams.
Preview frequently. Use the Mermaid Live Editor to test each change. It catches syntax errors fast.

These habits also apply if you're building other Mermaid diagrams. If you work with flowcharts, the annotation patterns in Mermaid flowchart scripting examples follow similar structural thinking.

How do you control the timeline axis and date display?

The axisFormat directive uses D3's time format specifiers. Common ones:

%Y-%m-%d → 2024-01-15
%b %d, %Y → Jan 15, 2024
%d/%m → 15/01

For the tickInterval, use values like:

1day, 2day, 7day
1week, 2week
1month

This matters when your project spans months. Without setting tickInterval, the axis can get cluttered with daily ticks for a 6-month project.

Can you use Mermaid Gantt charts in GitHub, GitLab, and documentation tools?

Yes. GitHub and GitLab both render Mermaid code blocks natively just wrap your chart in triple backticks with mermaid as the language identifier. Many static site generators like MkDocs, Docusaurus, and Hugo also support Mermaid through plugins.

The real advantage here is that your project timeline lives alongside your code. When the schedule changes, you update a text file and commit it. No exporting images, no broken links to external tools.

For teams already using Mermaid for class diagrams or other UML models, the Gantt syntax is a lightweight addition with no extra tooling needed.

How do you handle date ranges for tasks that start on a specific date?

Sometimes you need a task to start on a fixed date rather than after another task. Just put the date directly:

Compliance audit :ca1, 2024-04-01, 7d

You can mix fixed dates and dependencies in the same chart. Pin only the tasks that truly need a fixed date like external vendor deadlines and let everything else flow from dependencies.

What does a complete real-world example look like?

Here's a realistic project schedule combining everything above:

gantt dateFormat YYYY-MM-DD axisFormat %b %d excludes weekends title Website Redesign Project section Discovery Stakeholder interviews :done, disc1, 2024-02-01, 5d Competitor analysis :done, disc2, 2024-02-01, 7d Requirements doc :done, disc3, after disc2, 3d section Design Wireframes :done, des1, after disc3, 5d Visual mockups :active, des2, after des1, 7d Design review :milestone, des3, after des2, 0d section Development Set up CMS :dev1, after des3, 3d Build page templates :crit, dev2, after dev1, 10d Content migration :dev3, after dev2, 5d section Launch QA testing :test1, after dev3, 5d Stakeholder approval :crit, test2, after test1, 2d Go live :milestone, launch1, after test2, 0d

This shows completed work, active tasks, critical path items, milestones, and weekend exclusions all in about 20 lines of plain text.

Quick-reference syntax cheat sheet

Here's a condensed reference you can bookmark:

Start a chart: gantt
Set title: title My Project
Date format: dateFormat YYYY-MM-DD
Axis format: axisFormat %Y-%m-%d
Skip weekends: excludes weekends
Define a section: section Phase Name
Add a task: Task Name :id, startDate, duration
Add dependency: Task :id, after otherId, duration
Mark done: :done,
Mark active: :active,
Mark critical: :crit,
Add milestone: :milestone, id, date, 0d
Hide today line: todayMarker off

Your next step: build one now

Pick a real project you're working on whether it's a sprint plan, a content calendar, or a product launch. Write out the tasks, group them into three sections, add at least one dependency chain and one milestone, then paste it into the Mermaid Live Editor. You'll have a working Gantt chart in under 10 minutes.

Use this checklist before you commit any Gantt chart to your repo: