Mermaid Gantt Chart: Complete Syntax Guide with Examples

Mermaid Gantt charts let you embed project timelines directly in Markdown files using plain text. Write the schedule once, commit it alongside your code, and every Mermaid-compatible renderer — GitHub, GitLab, Notion, or MacMD Viewer — displays a polished visual chart. No spreadsheet, no project management subscription, no exported image to update every sprint.

TL;DR: Start with gantt, set dateFormat YYYY-MM-DD, add section groups, and define tasks with status modifiers (done, active, crit). Use after alias for dependencies and excludes weekends to skip non-working days. Preview locally with MacMD Viewer or online at mermaid.live.

What Are Mermaid Gantt Charts Good For?

Mermaid Gantt charts are the right tool when you need a project timeline that lives in version control. They work exceptionally well for software release plans embedded in READMEs, sprint schedules in engineering wikis, migration timelines in architecture decision records, and onboarding documentation where sequence and duration both matter.

They are not a replacement for MS Project, Jira, or Notion databases when you need resource allocation, percentage completion tracking, or multi-resource dependency graphs. The Mermaid Gantt is deliberately lean: it renders task bars, dependencies, a critical path overlay, and milestone markers — everything a development team needs to communicate a schedule without leaving Markdown.

Because the chart definition is plain text, pull request diffs show exactly what changed in the timeline. This is a meaningful advantage over embedded spreadsheet screenshots or exported PNGs, both of which require opening an external tool to inspect changes.

How Do You Write Basic Mermaid Gantt Syntax?

Every Mermaid Gantt chart starts with the keyword gantt on its own line, followed by configuration directives and task definitions. Here is a minimal working example:

gantt
    title Project Alpha
    dateFormat YYYY-MM-DD
    section Planning
        Requirements   : done, req, 2024-01-01, 2024-01-07
        Design         : active, des, 2024-01-08, 5d
    section Development
        Backend        : crit, back, 2024-01-13, 10d
        Frontend       : front, after back, 7d

Breaking down each line:

• title Project Alpha — optional chart title displayed above the diagram
• dateFormat YYYY-MM-DD — tells Mermaid how to parse the dates in your task definitions
• section Planning — creates a labeled group of tasks
• Requirements : done, req, 2024-01-01, 2024-01-07 — a completed task with alias req, running from Jan 1 to Jan 7
• Design : active, des, 2024-01-08, 5d — an in-progress task starting Jan 8 with a 5-day duration
• Backend : crit, back, 2024-01-13, 10d — a critical-path task with a 10-day duration
• Frontend : front, after back, 7d — a task that begins immediately after back completes

The task definition format follows this pattern:

TaskName : [crit,] [done|active,] [alias,] startDate, duration_or_endDate

All modifiers before the start date are optional and can be combined. crit can appear alongside done or active. The alias field must not contain spaces. Duration units are d (days), w (weeks), and h (hours).

How Do You Control Date Display and Axis Format?

Two directives control dates in a Mermaid Gantt chart: dateFormat governs how Mermaid parses the dates you write in task definitions, while axisFormat controls how those dates appear on the rendered horizontal axis.

gantt
    title Deployment Window
    dateFormat YYYY-MM-DD
    axisFormat %b %d
    section Release
        Staging deploy  : stg, 2024-03-01, 2d
        Smoke tests     : smoke, after stg, 1d
        Production      : crit, prod, after smoke, 1d

Common axisFormat tokens (using strftime syntax):

Set axisFormat to match the granularity of your chart. A month-long timeline benefits from %b %d, while a year-long roadmap is cleaner with %b %Y.

How Do Task Dependencies Work With the after Keyword?

Dependencies are the most powerful feature of Mermaid Gantt charts. The after keyword tells Mermaid to start a task immediately after one or more predecessors finish, without hardcoding a calendar date. This means you only need to adjust one task's duration to automatically shift everything downstream.

To use after, assign an alias to the predecessor task first:

gantt
    title API Integration
    dateFormat YYYY-MM-DD
    section Backend
        Schema design    : done, schema, 2024-02-01, 3d
        API endpoints    : api, after schema, 5d
        Unit tests       : tests, after api, 3d
    section Frontend
        Component build  : comp, after schema, 6d
        Integration      : crit, integ, after api comp, 4d

The Integration task uses after api comp — it waits for both api and comp to complete before starting. Mermaid resolves this to the latest end date among all referenced predecessors. This multi-dependency syntax (after alias1 alias2) is available from Mermaid v10.3 onward.

Dependency chains propagate automatically. If you extend the Schema design task from 3 days to 6 days, every downstream task shifts accordingly without any manual date editing.

What Does crit Do and How Do You Mark the Critical Path?

The crit modifier marks a task as part of the critical path. Mermaid renders these tasks with a distinct color — typically red in the default theme — so readers immediately identify which tasks cannot slip without delaying the project end date.

Add crit as the first modifier after the colon, before any status keyword:

gantt
    title Release Candidate Build
    dateFormat YYYY-MM-DD
    section Build
        Compile         : crit, done, compile, 2024-03-01, 1d
        Integration     : crit, done, integ, after compile, 2d
        QA pass         : crit, active, qa, after integ, 3d
    section Docs
        Release notes   : notes, 2024-03-01, 5d
        Changelog       : log, after notes, 1d
    section Deploy
        Staging         : crit, staging, after qa, 1d
        Production      : crit, prod, after staging, 1d

The Build and Deploy sections form the critical path (all marked crit). The Docs section runs in parallel but is not critical — a delay there would not push the go-live date. This visual distinction makes it immediately clear where management attention belongs.

How Do You Exclude Weekends and Holidays?

The excludes directive removes specific days from duration calculations. Mermaid ships with built-in support for weekends:

gantt
    title Sprint 12
    dateFormat YYYY-MM-DD
    excludes weekends
    section Sprint
        Planning        : done, plan, 2024-03-04, 1d
        Development     : dev, after plan, 5d
        Code review     : review, after dev, 2d
        Testing         : crit, test, after review, 3d
        Release         : crit, rel, after test, 1d

With excludes weekends, a 5d task starting Monday completes Friday — Saturday and Sunday are skipped. Without it, the same task would end Saturday. This produces more realistic timelines for development teams working standard business weeks.

You can also exclude specific calendar dates for public holidays:

excludes weekends, 2024-12-25, 2024-01-01

Multiple dates are comma-separated on the same excludes line.

How Do You Add Milestone Markers?

Milestones are zero-duration tasks that render as diamond markers on the timeline. They represent key delivery dates, sign-off gates, or review checkpoints without occupying schedule space.

gantt
    title Q1 Roadmap
    dateFormat YYYY-MM-DD
    section Milestones
        Alpha release    : milestone, alpha, 2024-01-31, 0d
        Beta release     : milestone, beta, 2024-02-29, 0d
        GA release       : milestone, ga, 2024-03-31, 0d
    section Engineering
        Core features    : core, 2024-01-01, 30d
        Beta hardening   : hard, after core, 28d
        Release prep     : crit, rel, after hard, 3d

The milestone keyword replaces the status modifier (done/active). The alias field still works normally, and the 0d duration is required to render the diamond shape. Milestones can also be placed after alias using the same dependency syntax as regular tasks.

Complete Example: Software Release Plan

Here is a production-ready Gantt chart for a software v2.0 release spanning four sections with dependencies, critical path markers, exclusions, and milestones. You can copy this directly into any .md file.

gantt
    title Software v2.0 Release Plan
    dateFormat YYYY-MM-DD
    axisFormat %b %d
    excludes weekends
 
    section Planning
        Kickoff meeting       : done, kickoff, 2024-01-08, 1d
        Requirements doc      : done, req, after kickoff, 4d
        Architecture review   : done, arch, after req, 3d
        Design spec sign-off  : milestone, m0, after arch, 0d
 
    section Development
        Database migrations   : crit, done, db, after arch, 5d
        Auth service          : crit, done, auth, after db, 6d
        Core API endpoints    : crit, done, api, after auth, 8d
        Admin dashboard       : dash, after arch, 10d
        Mobile SDK            : sdk, after api, 7d
 
    section QA & Hardening
        Integration tests     : crit, active, itests, after api, 5d
        Performance audit     : perf, after api, 3d
        Security review       : crit, sec, after itests, 3d
        Beta candidate        : milestone, beta, after sec, 0d
 
    section Release
        Staging deploy        : crit, stg, after beta, 2d
        Stakeholder sign-off  : crit, signoff, after stg, 1d
        Production rollout    : crit, prod, after signoff, 1d
        GA announcement       : milestone, ga, after prod, 0d

This chart demonstrates all major features working together: excludes weekends for realistic durations, after alias dependencies propagating through four sections, crit marking the delivery-critical path in red, done/active showing progress, and milestone markers for sign-off gates. Adjusting any task duration automatically shifts everything downstream — no manual date editing required.

Where Does Mermaid Gantt Render?

Mermaid Gantt charts render natively in the following environments:

• GitHub — any .md file with a ```mermaid code fence renders inline since 2022. READMEs, issues, pull requests, and wikis all support it.
• GitLab — native Mermaid rendering in Markdown files, wikis, and issue descriptions.
• Notion — create a code block, set language to mermaid, and Notion renders the diagram in-page.
• Confluence — requires the Mermaid plugin from the Atlassian Marketplace; renders inside page blocks.
• MacMD Viewer — native macOS app (download here) that renders all Mermaid diagram types in local .md files. Open a file and the Gantt chart appears instantly with live file watching. The bundled QuickLook extension renders diagrams when you press Space in Finder. No internet connection or browser extension required. $19.99 one-time.
• Mermaid Live Editor — free browser playground. Paste syntax on the left, see the output on the right, export as SVG or PNG. Ideal for quick iteration before committing.
• VS Code — install the Markdown Mermaid extension and use Cmd+Shift+V to toggle the preview pane.

For a comparison of online rendering options, see the online Mermaid diagram tools guide. To export a Gantt chart as a static image, the Mermaid-to-PNG converter handles batch exports without a local renderer.

What Are the Limitations Compared to MS Project or Jira?

Mermaid Gantt charts cover the essentials for development team communication, but they are not project management software. Key limitations to be aware of:

No resource allocation. You cannot assign tasks to specific people or track per-person utilization. Every task is unowned in the diagram itself — ownership lives in the surrounding documentation.

No partial completion percentage. Progress is binary: a task is either done, active, or unstarted. There is no 60% state. The active modifier covers everything in flight.

No swimlanes by assignee. Sections group tasks by phase or component, not by team member. You cannot produce a resource-view Gantt showing each person's workload.

No baseline tracking. Mermaid has no concept of planned-vs-actual. If a task slips, you update the date — there is no built-in comparison to the original plan.

Limited styling. You can apply Mermaid themes (default, dark, neutral, forest) but cannot style individual task bars with custom colors beyond the crit overlay.

For teams that need these features, Jira's roadmap view, Linear milestones, or a dedicated project management tool is the right choice. For teams that want a timeline embedded in their documentation repository — versioned, diffable, and rendered anywhere Markdown renders — Mermaid Gantt is the pragmatic solution.

How Do You Preview Mermaid Gantt Charts Locally?

Three practical options depending on your workflow:

1. MacMD Viewer ($19.99) — open any .md file containing a Mermaid Gantt and see it rendered instantly. Supports live file watching, so edits in your text editor appear in the preview in real time. The QuickLook extension renders Gantt charts in Finder without opening the app. Available on the Mac App Store.
2. Mermaid Live Editor — free browser tool. Paste your Gantt syntax and see the output immediately. Useful for validating syntax before committing.
3. VS Code — with the Markdown Mermaid extension installed, Cmd+Shift+V opens a side-by-side preview that renders Gantt charts inline.

For a broader comparison of rendering tools, see the Mermaid Live Editor guide.

Conclusion

Mermaid Gantt chart syntax covers everything you need to communicate a project schedule inside a Markdown file: date formats, sections, task status modifiers, dependency chains with after, critical path highlighting with crit, weekend exclusions, and milestone markers. The complete software release example above can be copied directly into any README or wiki page and adapted in minutes.

For other diagram types, see the Mermaid flowchart syntax guide, the Mermaid sequence diagram guide, and the Mermaid ER diagram guide. To render all of these locally on Mac without a browser, MacMD Viewer ($19.99) opens any .md file and displays every Mermaid diagram type instantly.