Mermaid Kanban Board Guide: Build Project Boards with Code

# Mermaid Kanban Board Guide: Build Project Boards with Code

Kanban boards are usually trapped inside project management tools. That works for day-to-day task tracking, but it is not ideal for documentation, architecture planning, RFCs, onboarding notes, or GitHub pull requests.

Mermaid changes that. With Mermaid's kanban syntax, you can create lightweight project boards as text, keep them in your repo, review them in pull requests, and render them in tools that support Mermaid diagrams.

This guide shows how to create practical Mermaid Kanban boards for product work, engineering planning, bug triage, content pipelines, and release checklists.

What Is a Mermaid Kanban Board?

A Mermaid Kanban board is a text-based diagram that organizes tasks into columns such as Todo, In Progress, Review, and Done. Instead of dragging cards in a web app, you define the board with code.

A simple board looks like this:

kanban
  Todo
    Write product spec
    Draft API contract
  In Progress
    Build auth flow
  Review
    QA signup page
  Done
    Create landing page

You can paste that into MermaidEditor.lol, preview it instantly, and export the rendered diagram for docs or presentations.

Why Use Mermaid Instead of a Traditional Kanban Tool?

Mermaid is not trying to replace Jira, Linear, Trello, or GitHub Projects for active task management. It is better for boards that belong in documentation.

Use Mermaid Kanban when you need:

- A roadmap snapshot in a README

- A project status board inside an RFC

- A release checklist that is version-controlled

- A bug triage board for a postmortem

- A content pipeline in a public documentation repo

- A simple planning artifact that should survive tool migrations

The biggest advantage is reviewability. A Mermaid board is plain text, so changes show up clearly in git diffs.

Basic Mermaid Kanban Syntax

Start with the kanban keyword. Then define columns and cards underneath them.

kanban
  Backlog
    Add OAuth login
    Improve empty states
    Create API docs
  In Progress
    Build billing dashboard
  Review
    Test webhook retries
  Shipped
    Launch pricing page

The indentation matters. Columns are top-level entries under kanban, and cards are indented below each column.

Product Roadmap Example

Kanban boards are useful for roadmap communication because they show priority and progress without needing a full project management system.

kanban
  Next
    Customer interviews
    Pricing experiment
    Homepage copy refresh
  Building
    Usage dashboard
    Team invitations
  Validating
    Stripe webhook alerts
    Cancellation survey
  Shipped
    Free trial flow
    Onboarding checklist

This is ideal for changelog posts, internal updates, or founder updates where you want a simple visual summary.

Engineering Release Checklist

For engineering teams, Mermaid Kanban works well as a release checklist inside a pull request or deployment runbook.

kanban
  Before Deploy
    Run unit tests
    Run typecheck
    Check env variables
    Review migrations
  Deploying
    Push to production
    Watch logs
  Verify
    Smoke test signup
    Test billing webhook
    Check sitemap
  Done
    Post release note
    Archive branch

Because the board is stored with the code, it becomes part of the release history.

Bug Triage Board

Mermaid Kanban is also useful for postmortems and triage documents.

kanban
  Reported
    Login redirect loop
    Dashboard chart blank
  Reproduced
    Billing webhook duplicate
  Fixing
    API timeout handling
  Fixed
    Broken sitemap route
  Won't Fix
    Legacy browser CSS issue

This makes the state of an incident easy to understand without requiring everyone to open an external tool.

Best Practices

Keep the board small. Mermaid Kanban diagrams are best for summaries, not huge operational boards. If you have 200 tasks, use Linear or Jira.

Use short card names. A card should be readable at a glance. Put details in the surrounding document, not inside the board.

Use stable column names. Common sets include:

- Backlog, Next, In Progress, Review, Done

- Planned, Building, Validating, Shipped

- Reported, Reproduced, Fixing, Fixed

- Draft, Editing, Scheduled, Published

Update the board when the document changes. A stale diagram is worse than no diagram.

Mermaid Kanban vs Flowcharts

Use a flowchart when you need to show process logic, decisions, or dependencies.

Use a Kanban board when you need to show work status.

A flowchart answers: what happens next?

A Kanban board answers: where is each item right now?

For larger docs, you can use both. Start with a flowchart explaining the system, then add a Kanban board showing rollout status.

Preview and Export

The fastest way to work with Mermaid Kanban diagrams is to paste your code into MermaidEditor.lol. You can preview changes live, switch themes, and export diagrams for docs, slides, or tickets.

If you are writing technical documentation, keep the Mermaid source in the same repo as the doc. That way your board can evolve with the project instead of becoming a forgotten screenshot.

Final Thoughts

Mermaid Kanban boards are not for replacing your team's project management tool. They are for making project status visible inside documentation.

Use them for roadmaps, release notes, triage summaries, and planning docs where the board itself should be version-controlled.

If your status update belongs in git, Mermaid Kanban is a clean way to draw it.