Mermaid Gantt Charts — Timeline and Schedule Visualization

In this tutorial, you will learn about Mermaid Gantt Charts. We cover key concepts, practical examples, and best practices to help you master this topic.

Mermaid Gantt charts visualize project timelines and schedules, showing tasks, durations, dependencies, and milestones in an easy-to-read horizontal bar chart format.

In this lesson, you will learn Gantt chart syntax, task definitions with dates, dependencies between tasks, milestone markers, section grouping, and formatting options for documentation.

What You'll Learn

You will master Mermaid Gantt charts: setting date formats, defining tasks with start and end dates, creating dependencies, grouping tasks into sections, adding milestones, and styling.

Why It Matters

Gantt charts communicate timelines visually, making them essential for release plans, project roadmaps, and sprint schedules in project documentation and developer guides.

Real-World Use

DodaTech uses Gantt charts in quarterly planning documents to show release schedules for Doda Browser, DodaZIP, and Durga Antivirus Pro. Stakeholders understand the timeline in 30 seconds.

gantt
    title DodaZIP Release Schedule
    dateFormat  YYYY-MM-DD
    section Planning
    Requirements Review      :done, 2026-07-01, 2026-07-07
    Architecture Design      :done, 2026-07-08, 2026-07-21
    section Development
    Core Compression         :active, 2026-07-22, 2026-08-11
    UI Integration           :2026-08-01, 2026-08-18
    section Testing
    Unit Tests               :2026-08-12, 2026-08-18
    Performance Testing      :2026-08-19, 2026-08-25
    Beta Release             :milestone, 2026-08-25, 0d

def create_gantt_chart(title, sections, date_format="YYYY-MM-DD"):
    """Generate Mermaid Gantt chart syntax."""
    lines = ["gantt", f"    title {title}", f"    dateFormat {date_format}", ""]
    for section_name, tasks in sections:
        lines.append(f"    section {section_name}")
        for task in tasks:
            status = task.get("status", "")
            status_str = f":{status}," if status else ":"
            lines.append(f"    {task['label']}{status_str}{task['start']}, {task['end']}")
        lines.append("")
    return "\n".join(lines)

chart = create_gantt_chart("Project Plan", [
    ("Phase 1", [
        {"label": "Research", "start": "2026-07-01", "end": "2026-07-07", "status": "done"},
        {"label": "Prototype", "start": "2026-07-08", "end": "2026-07-21", "status": "active"},
    ]),
])
print(chart)

def add_milestone(gantt_text, label, date):
    """Add a milestone marker to a Gantt chart."""
    return gantt_text + f"    {label}: milestone, {date}, 0d\n"

chart = "gantt\n    dateFormat YYYY-MM-DD\n    section Dev\n    Coding: 2026-07-01, 2026-07-15\n"
print(add_milestone(chart, "Code Complete", "2026-07-15"))

def set_gantt_style(gantt_text, theme="base"):
    """Configure Gantt chart styling."""
    return f"---\n---\n{gantt_text}\n    gantt\n        axisFormat %Y-%m-%d\n        tickInterval 1week"

chart = "gantt\n    dateFormat YYYY-MM-DD\n    section Work\n    Task1: 2026-07-01, 2026-07-07"
print(set_gantt_style(chart))

Teacher Mindset

Think of a Gantt chart as a visual contract with your team. It says: here is what we plan to do, in what order, and by when. When things change (and they always do), update the Gantt chart. An outdated Gantt chart is worse than none because it shows a plan that no longer exists. Keep it honest and current.

Common Mistakes in Gantt Charts

1. Tasks That Are Too Large

A task labeled "Development" that spans 3 months tells readers nothing. Break into weekly or biweekly tasks with specific deliverables.

2. No Dependencies Between Tasks

Without dependency lines, readers cannot tell which tasks block others. Use task IDs and dependency syntax: task1, after task2.

3. Unrealistic Time Estimates

Tasks estimated too optimistically create misleading charts. Add buffer time. A task that takes 5 days should show 7 in the chart.

4. Missing Milestones

Milestones mark important dates: releases, reviews, decision points. Without milestones, a Gantt chart is just a list of tasks with no anchor points.

5. No Progress Indicators

Use done, active, and crit status markers to show actual progress versus plan. A chart showing all tasks as planned with no progress is not useful.

Practice Questions

1. What is the difference between a task and a milestone in a Gantt chart? A task has duration (start and end dates). A milestone is a point in time (a single date with 0 duration) marking an important event.

2. How do you show task dependencies in Mermaid Gantt? Use the after keyword: Task2, after Task1. This creates a dependency line showing Task2 starts after Task1 completes.

3. What status keywords are available for Gantt tasks? Done (completed), active (in progress), and crit (critical path). Use these to show progress and highlight important tasks.

4. How do you format dates in Mermaid Gantt charts? Set the dateFormat at the top. Common formats: YYYY-MM-DD, DD-MM-YYYY, MM-DD-YYYY. Use the same format for all dates in the chart.

5. Challenge: Create a Gantt chart for a 3-month software release cycle. Include sections for planning, development, testing, and deployment. Add milestones for design review, beta release, and production launch.

FAQ

Mini Project

Create a Gantt chart for a project you are working on or planning. Include at least 3 sections, 10 tasks, 2 milestones, and dependency links. Use status markers to show progress. Embed it in a planning document.

What's Next

Excalidraw in the next lesson.