Skip to main content

How to Create Gantt Charts in Confluence with Mermaid

· 13 min read
NGPilot
NGPilot
NGPilot

Gantt charts are one of the most widely used visual tools in project management. They give teams a clear, time-based view of who is doing what, when tasks start and end, and how dependencies chain together across a project lifecycle. Whether you are planning a software release, coordinating a marketing campaign, or managing a sprint backlog, a Gantt chart turns a flat task list into a timeline your whole team can read at a glance.

Confluence is where many teams already store their project documentation, meeting notes, and decision records. Embedding Gantt charts directly on Confluence pages keeps your project visuals alongside the context your team needs, instead of burying timelines in a separate project management tool that nobody checks. With Mermaid Plus for Confluence, you can write Gantt charts using plain text syntax and see them rendered instantly on the page.

In this tutorial, you will learn how to create Gantt charts in Confluence using Mermaid syntax. Every example is copy-paste ready, so you can drop it straight into a Confluence page and start customizing it for your own projects.

Why Gantt Charts in Confluence?​

Teams reach for Gantt charts when they need to visualize when work happens and what depends on what. Unlike a simple task list or a Kanban board, a Gantt chart places every task on a time axis, making it easy to spot scheduling conflicts, idle periods, and critical-path bottlenecks. This makes Gantt charts especially useful for:

  • Project kickoffs where stakeholders need to see the full timeline before approving scope
  • Cross-team coordination so engineering, design, QA, and marketing can align on handoff dates
  • Status reporting that gives executives a visual summary without digging through Jira boards
  • Onboarding new team members who need to understand the project cadence and upcoming milestones

Confluence is the natural home for this kind of documentation. Your project briefs, architecture decision records, and retrospective notes already live there. Adding a rendered Gantt chart to the same page means the timeline is always one scroll away from the context that explains it. When dates change, you update the Mermaid code and republish. No exports, no screenshots, no broken image links.

Mermaid's Gantt syntax is purpose-built for project timelines. It supports task dependencies, milestones, status indicators, sections, date exclusions, and custom date formats. With Mermaid Plus for Confluence, you get a code editor right inside the Confluence page, with live preview and full version history.

Step-by-Step: Create Your First Gantt Chart​

Follow these steps to go from a blank Confluence page to a fully rendered Gantt chart.

Step 1 -- Install Mermaid Plus for Confluence​

Head to the Atlassian Marketplace and search for Mermaid Plus for Confluence. Click Get App and follow the installation prompts. Once installed, the Mermaid Plus macro becomes available on every space in your Confluence instance.

If your organization pre-approves apps, check with your Confluence admin first. The app supports Confluence Cloud and Confluence Data Center.

Step 2 -- Insert the Mermaid Macro​

Open any Confluence page in edit mode. Type /mermaid in the editor and select the Mermaid Plus macro from the dropdown. A code editor panel appears where you can write Mermaid syntax.

Step 3 -- Write the gantt Header​

Start every Gantt chart with the gantt keyword, then set your date format and add an optional title:

gantt
  title My First Gantt Chart
  dateFormat YYYY-MM-DD

The dateFormat directive tells Mermaid how to parse the dates you provide. YYYY-MM-DD is the most common format, but Mermaid also supports MM/DD/YYYY, DD-MM-YYYY, and others. The title appears at the top of the rendered chart.

Step 4 -- Add Tasks and Milestones​

Define tasks with a task ID, display name, start date, and duration. Chain tasks together with the after keyword:

gantt
  title My First Gantt Chart
  dateFormat YYYY-MM-DD

  section Planning
    Requirements gathering  :done, req, 2026-05-01, 10d
    Architecture design     :active, arch, after req, 5d

  section Development
    Frontend build          :dev-fe, after arch, 15d
    Backend API             :dev-be, after arch, 12d
    Go-live milestone       :milestone, launch, after dev-fe, 0d

Each task line follows this pattern: taskID : status, taskID, startOrDependency, duration. The status flags (done, active, or no flag for future) control how the bar appears in the rendered chart. Milestones use the milestone keyword and have zero duration.

Step 5 -- Save and Publish​

Preview the Gantt chart inside the macro editor to verify it renders correctly. Check that dependencies flow in the right order and that your date format is consistent throughout. When you are happy with the result, click Save on the macro, then Publish the Confluence page. Your Gantt chart is now part of your living project documentation.

Mermaid Gantt Syntax Reference​

Here is a quick-reference table for the most commonly used Gantt chart elements in Mermaid. Bookmark this section and come back to it whenever you need a syntax reminder.

ElementSyntaxDescription
Chart headerganttStarts a Gantt chart
Titletitle My ChartDisplays a title above the chart
Date formatdateFormat YYYY-MM-DDSets how Mermaid parses your dates
Axis formataxisFormat %b %dControls how dates appear on the time axis
Sectionsection Phase NameGroups tasks into labeled sections
Task (basic)task1 : Task Name, 2026-01-01, 30dA task with start date and duration
Task (with ID)task1 : Task Name, 2026-01-01, 30dNamed task with ID for dependencies
Task (end date)task1 : Task Name, 2026-01-01, 2026-01-31A task defined by start and end date
Dependencytask2 : Task Name, after task1, 14dTask starts after another task finishes
Done status:done, task1, ...Marks task as completed (grayed out)
Active status:active, task1, ...Marks task as in progress (highlighted)
Milestone:milestone, m1, 2026-03-15, 0dA zero-duration diamond marker
Exclusionexcludes weekendsExcludes named days from the timeline
Comment%% This is a commentInline comment, not rendered
Critical path:crit, task1, ...Highlights task on the critical path

3 Copy-Paste Gantt Chart Examples​

Below are three practical examples you can paste directly into the Mermaid Plus macro in Confluence. Each example demonstrates a different real-world project scenario.

Example 1 -- Software Release Timeline​

This Gantt chart models a typical software release cycle from design through production deployment. It uses sections to separate phases, status flags to show progress, and dependencies to enforce a realistic task order.

gantt
  title Software Release v2.0 Timeline
  dateFormat YYYY-MM-DD
  axisFormat %b %d

  section Design
    UX research           :done, ux, 2026-04-01, 7d
    Wireframes            :done, wire, after ux, 5d
    Visual design         :done, vis, after wire, 7d

  section Development
    Frontend sprint 1     :active, fe1, 2026-04-21, 10d
    Frontend sprint 2     :fe2, after fe1, 10d
    Backend API           :be, 2026-04-21, 14d
    Integration           :int, after fe2, 5d

  section Testing
    QA regression         :qa, after int, 7d
    User acceptance       :uat, after qa, 5d
    Bug fixes             :fix, after uat, 5d

  section Release
    Staging deploy        :stage, after fix, 2d
    Production deploy     :prod, after stage, 1d
    Post-release monitor  :mon, after prod, 5d

Use this chart as a starting point for your own release planning. Add tasks for documentation updates, performance testing, or security audits as your release process requires. The done, active, and future states let readers see the current progress at a glance.

Example 2 -- Marketing Campaign Launch​

This example models a multi-channel marketing campaign with content creation, review cycles, and a hard launch date. It demonstrates how milestones mark key deadlines and how parallel tracks (blog content, email, social media) run concurrently.

gantt
  title Q3 Product Launch Campaign
  dateFormat YYYY-MM-DD
  axisFormat %b %d

  section Strategy
    Market research       :done, research, 2026-06-01, 7d
    Campaign brief        :done, brief, after research, 3d
    Messaging framework   :done, msg, after brief, 4d

  section Content
    Blog post drafts      :active, blog, after msg, 10d
    Video production      :video, after msg, 14d
    Landing page copy     :lp, after msg, 5d
    Email sequences       :email, after msg, 7d

  section Review
    Legal review          :legal, after blog, 5d
    Brand review          :brand, after lp, 3d
    Revisions             :rev, after legal, 3d

  section Launch
    Content freeze        :milestone, freeze, after rev, 0d
    Social media schedule :social, after freeze, 3d
    Email blast setup     :blast, after freeze, 2d
    Campaign go-live      :milestone, launch, 2026-07-15, 0d

  section Post-Launch
    Performance report    :report, after launch, 7d
    Retrospective         :retro, after report, 1d

This chart highlights two important patterns. First, multiple tasks share the same dependency (after msg), which creates parallel tracks that start simultaneously. Second, the milestone keyword creates diamond markers on the timeline for events with zero duration, making launch dates and deadlines visually distinct from work tasks.

Example 3 -- Sprint Planning​

This example shows a two-week Agile sprint with stories grouped by epic. It uses compact durations and a Monday-to-Friday working pattern via the excludes keyword, which prevents weekends from inflating the timeline.

gantt
  title Sprint 14 — May 5-16
  dateFormat YYYY-MM-DD
  axisFormat %b %d
  excludes weekends

  section Sprint Setup
    Sprint planning       :done, plan, 2026-05-05, 1d
    Backlog refinement    :done, refine, 2026-05-05, 1d

  section Epic: User Dashboard
    Dashboard API         :active, api, 2026-05-06, 4d
    Dashboard UI          :dash, after api, 3d
    Dashboard testing     :dtest, after dash, 2d

  section Epic: Notifications
    Email templates       :tmpl, 2026-05-06, 3d
    Notification service  :notif, after tmpl, 3d
    Push integration      :push, after notif, 2d

  section Sprint Close
    Code review           :review, 2026-05-14, 1d
    Sprint demo           :milestone, demo, 2026-05-16, 0d
    Retrospective         :retro, after demo, 0d

The excludes weekends directive is essential for sprint timelines because it prevents Saturday and Sunday from appearing as working days. Mermaid automatically extends the task bars to account for excluded days, so a 3-day task starting on Friday will correctly span Friday, Monday, and Tuesday.

Tips for Complex Gantt Charts​

As your Gantt charts grow beyond ten or fifteen tasks, readability and maintainability become important. These tips help you keep large charts organized and accurate.

Sections are the primary organizational tool in Mermaid Gantt charts. They create labeled rows that visually separate phases, epics, or teams. Every task between two section declarations belongs to the same group. Use section names that match how your team talks about the work: "Phase 1", "Backend", "Epic: Search", or "Q3" are all good choices.

Chain Dependencies Carefully​

The after keyword is powerful but can create confusing charts if used carelessly. Follow these guidelines:

  • One dependency per task is the most readable pattern. If a task depends on two predecessors, pick the one that finishes latest.
  • Avoid circular dependencies. If task B depends on task A, task A cannot depend on task B. Mermaid will fail to render the chart.
  • Use task IDs that are short and descriptive. IDs like ux, fe1, and stage are easier to read in dependency chains than task1, task2, task3.

Exclude Non-Working Days​

Use excludes weekends for charts that represent working-day timelines. You can also exclude specific dates like company holidays:

excludes weekends, 2026-07-04, 2026-12-25

Mermaid adjusts all task durations automatically when exclusions are present. This prevents your chart from showing work happening on days when nobody is in the office.

Use Milestones for Key Dates​

Milestones are zero-duration events rendered as diamonds on the timeline. They are ideal for marking launch dates, approval deadlines, review gates, and external dependencies. A good rule of thumb is one milestone per phase of your project. Too many milestones make the chart noisy; too few make it hard to spot important dates.

Use Status Flags Honestly​

Mermaid supports three task states: done (completed, grayed out), active (in progress, highlighted), and the default future state. Update these flags as your project progresses. An accurate Gantt chart is a useful communication tool. An outdated one erodes trust in the timeline.

Keep Task Names Concise​

Long task names push the chart wider and reduce the space available for the time axis. Aim for two to four words per task name. If you need more detail, add a comment or link to a Jira ticket in a note on the Confluence page.

Use the Critical Path Flag Sparingly​

The crit status flag highlights a task in red, marking it as a critical-path item. This is useful for drawing attention to tasks that will delay the entire project if they slip. Reserve crit for the handful of tasks that truly block downstream work. Highlighting every task as critical defeats the purpose.

Break Very Large Charts into Multiple Diagrams​

If a single Gantt chart exceeds 25 to 30 tasks, consider splitting it into separate charts per phase or per team. Confluence supports multiple Mermaid macros on the same page, so you can show a high-level overview chart at the top, followed by detailed phase-specific charts below. Link them with a brief prose explanation of what each chart covers.

Use Styling for Emphasis​

Mermaid supports inline styling with the style keyword. You can change the color of specific task bars to call out risks, blockers, or stretch goals:

style fe1 fill:#ffcccc,stroke:#ff0000

Apply styling judiciously. One or two highlighted tasks draw attention. Ten highlighted tasks create visual noise.

Common Mistakes to Avoid​

  • Forgetting the gantt keyword. Every Gantt chart must start with gantt on its own line. Without it, Mermaid does not know what type of diagram to render.
  • Inconsistent date formats. If you set dateFormat YYYY-MM-DD, every date in the chart must follow that format. Mixing 2026-05-01 and 05/01/2026 will cause parse errors.
  • Missing commas in task definitions. Task lines require commas between the status, task ID, date, and duration. A missing comma is the most common syntax error in Mermaid Gantt charts.
  • Using after with a task ID that does not exist. The dependency target must match a task ID defined earlier in the chart. A typo in the task ID will produce a confusing error or an incorrect layout.
  • Omitting the 0d duration for milestones. Milestones must have a duration of 0d. Without it, Mermaid treats them as regular tasks with a one-day duration.
  • Placing title after tasks. The title, dateFormat, axisFormat, and excludes directives must appear before any task definitions. Putting them after a section or task line will cause a parse error.

Gantt charts are a practical, high-leverage addition to your Confluence documentation. A well-structured Mermaid Gantt chart takes minutes to create, lives alongside your project context, and stays current with a simple text edit. Install Mermaid Plus for Confluence, paste one of the examples above into a page, and start building your project timelines today.