Skip to content
MermaidViewer

Planning diagram

Mermaid kanban diagram

Mermaid kanban diagram syntax for columns and cards, with a sprint board you can keep in Markdown.

By MermaidViewer editorsPublished Updated

Basic kanban board example

Basic kanban board example diagram
mermaid
kanban
  todo[To do]
    t1[Write API docs]
    t2[Design pricing page]@{ priority: 'High' }
  doing[In progress]
    t3[AI diagram editor]@{ assigned: 'sam', ticket: MV-42 }
  review[Review]
    t4[Dark mode]
  done[Done]
    t5[Launch landing page]
Open in the live editor

Mermaid kanban diagrams render a board of columns and cards from an indented list. Each top-level item is a column; items indented beneath it are cards.

Cards can carry metadata like ticket ids, assignees and priority, which makes kanban diagrams a lightweight way to snapshot project status in docs and reports.

When to use a kanban board

  • Sprint status snapshots
  • Release checklists
  • Personal task boards
  • Roadmap status in READMEs

Kanban Board syntax reference

SyntaxWhat it does
kanbanStart a kanban board.
id[Column title]A column (top-level item).
id[Card text]A card (indented under a column).
@{ ticket: X, assigned: 'name', priority: 'High' }Card metadata.
priority: 'Very High' | 'High' | 'Low' | 'Very Low'Priority values.

Kanban Board examples

Columns and the cards inside them are the whole board. A mermaid kanban diagram is a snapshot you can commit next to a README. Indent is what makes a line a card instead of another column. The syntax table shows the shape. The mistakes are almost all indentation and stale status.

Columns and cards

kanban opens the board. A top-level line is a column. Todo is a column whose title is Todo. A line indented beneath it's a card: task1[Write spec]. The id is task1 and the label is Write spec. The next column, Doing, returns to the left margin. Its cards indent again.

Ids have to be unique on the board. The label can change every time the wording gets clearer. The id should not, because it's how you talk about the card in review. task1 can stay while the label goes from "Write spec" to "Write the refund spec."

This picture has no dates and no assignees in the simple form. If the fact you need is "this starts Thursday," use a Gantt chart. If the fact is "this felt hard for the new hire," use a journey. The kanban column is a status. Moving a card is cutting the line from one column and pasting it under another, with the indent fixed.

Keep columns to a handful. Todo, Doing, and Done match how people already talk. A column per person becomes an org chart, and the board stops answering "what is blocked."

Worked example

Four cards, three columns. Spec and copy aren't started. The form is in progress. The page has shipped.

Mermaid diagram
mermaid
kanban
  Todo
    task1[Write spec]
    task2[Review copy]
  Doing
    task3[Build form]
  Done
    task4[Ship page]
Open in the live editor

Todo has two cards because both are waiting. task3 is the only line under Doing, so the board says the team is building the form and not also reviewing copy. That may be wrong on purpose. If review is happening now, move task2 under Doing and indent it to match task3. Leaving it under Todo while the work happens is how these diagrams rot. They don't update themselves.

task4[Ship page] in Done means the page is finished, not that shipping is a task you're about to do. Name the card for the outcome if it lives in Done, or for the work if it lives in Todo. "Ship page" in Todo reads as future work. The same words in Done read as a record. Pick the reading that matches the column.

There's no arrow from Todo to Done. Order of columns is left to right in the file. Put Done last so the board reads the way a wall board reads. Treat the file as a snapshot with a date in the caption. Next week's board is a new commit, not an edit you hope everyone noticed.

When this is the wrong diagram

A Gantt chart is the better picture when a card needs a start and a duration. A timeline is the better picture when you're recording when something happened, not where it sits in a workflow. Use a kanban diagram for a status snapshot.

Common mistakes

  1. A card at the same indent as Todo. It becomes another column, titled with the card text, instead of a card inside Todo. Indent the card one level.
  2. Reusing task1 on two cards. Ids are unique. A second spec is task5, even if the label looks similar.
  3. Dates and durations in the label because the column could not say "Thursday." That's a schedule. Move it to a Gantt chart.
  4. Done in the middle of the file and Todo at the end. Column order is file order. Read the board left to right before you publish.

Where to go next

The AI kanban generator will sort a task list into columns. Check the indents in the editor, and the cheat sheet has the column and card lines. The sprint kanban template is a fuller board if you want more than four cards.

Columns are the process, cards are the work

A column is a state the team will move a card through. If nobody moves a card into "Blocked" as its own column, do not invent the column to look complete. A card is one piece of work with a unique id. The id is for you, the label is for the reader, and they can differ: id pay-3, label "Retry failed charges".

Indentation is the whole syntax. A card that lines up with the column name becomes a new column. Look at the rendered board and count columns before you count cards. The sprint template is a board with the indents already right, and the AI kanban generator will sort a list if you then fix the ids.

A board with empty columns is fine. An empty column that you will never use is a column to delete.

Tips and best practices

  • Give every column and card a unique id.
  • Use metadata sparingly — the board is a snapshot, not a full tracker.
  • Configure ticketBaseUrl to turn ticket ids into links.

Generate a kanban board with AI

Not sure where to start? Describe what you need and the AI kanban board generator writes the Mermaid code for you. Try prompts like:

  • “Kanban board for a website redesign”
  • “Content calendar board”
  • “Hiring pipeline board”

Kanban Board templates

Kanban Board FAQ

Can Mermaid kanban cards link to tickets?

Yes. Add ticket: ID to a card and set ticketBaseUrl in the kanban config (for example https://github.com/org/repo/issues/#TICKET#) to link each card.