Mermaid Kanban Diagram Tutorial: Text-Based Boards with Columns and Cards

A kanban board is the everyday picture of work in progress: columns for the stages of your workflow, cards moving across them from "To Do" to "Done." Full kanban tools are interactive apps, but there are moments when you just want a board as a static, text-based artifact - a snapshot in a README, a planned board in an RFC, a sprint layout in a document that versions with the code. Mermaid's kanban diagram provides exactly that, rendering columns and cards from indented text much like the mindmap syntax.

This guide covers the kanban syntax, including the metadata you can attach to cards, with examples for the Mermaid editor at /diagram-tools/mermaid-editor. The rendered board opens as an editable diagram in Atlas Diagram Studio at /diagrams, ready to share or embed. It is a newer addition to Mermaid, and it pairs naturally with the other planning-oriented diagrams; to draft a board from a description of your workflow, the AI diagram generator at /diagram-tools/ai-diagram-generator can produce a starting layout you then edit.

Columns and cards

A kanban diagram starts with the keyword "kanban". Below it, each column is declared by an identifier and a bracketed label, such as "todo[To Do]", written at the top indentation level. The cards belonging to a column are the lines indented beneath it, exactly like children under a parent in a mindmap. So a "To Do" column with two cards is the column line followed by two indented card lines, and the indentation is what assigns each card to its column.

A card at its simplest is just its text on an indented line, but Mermaid also lets you give a card an explicit id in brackets, as in "id1[Design the API]", which is useful when you want to reference or style it. The order of columns left to right on the rendered board follows the order you declare them, and the order of cards top to bottom within a column follows the order you list them, so the source reads as a direct transcript of the board.

Card metadata

Where the kanban diagram goes beyond a plain list is the metadata you can attach to a card, giving each one the attributes a real board tracks. The bullets below cover the structure and the common metadata keys.

• Begin the diagram with the "kanban" keyword on its own line.
• Declare a column as an id and bracketed label at the top indent: "doing[In Progress]".
• Add cards as indented lines under their column, one card per line.
• Give a card an explicit id for reference: "t1[Write the migration]".
• Attach metadata in an "@{ ... }" block after a card, such as assignee and priority.
• Common metadata keys include "assigned" for an owner, "priority" for importance, and "ticket" for an issue reference.
• Priority values like "Very High", "High", "Low", and "Very Low" can drive the card's visual emphasis.

What a text board is good for

A Mermaid kanban is deliberately a snapshot, not a live tool - it does not update as work moves, and it has no drag-and-drop. That framing tells you where it fits. It shines as documentation of a board at a point in time: the sprint plan captured in a planning doc, the proposed workflow in an RFC, a teaching example of what a board looks like, or a status picture embedded in a README that updates in the same commit as the work it describes. For running day-to-day work, a real kanban application remains the right tool.

The advantage of the text form is everything that comes with being text: it versions in your repository, it is reviewed in pull requests, and it diffs cleanly so you can see exactly which cards moved between two versions. That makes it a genuine complement to a live board rather than a replacement - the live board is where work happens, and the Mermaid board is how you capture and communicate a particular state of it in durable documentation.

Kanban among the planning diagrams

The kanban diagram sits alongside Mermaid's other planning and workflow diagrams, and choosing among them is about what you are communicating. A kanban shows work by stage at a moment in time; a Gantt chart shows tasks against a schedule with durations and dependencies; a timeline shows events in order without a real time axis. For the logic of how work moves between stages - the rules and decisions - a flowchart from /diagram-tools/flowchart-maker is the fit, and a board complements it by showing the current contents of each stage.

Author your board in the Mermaid editor at /diagram-tools/mermaid-editor, refine and style it in Atlas Diagram Studio at /diagrams, and embed it wherever your team reads status. For the full range of Mermaid diagrams and how they combine into a documentation set, the complete Mermaid guide at /guides/mermaid-js-complete-guide is the reference, and the guide on generating diagrams from code at /guides/how-to-generate-diagrams-from-code covers keeping such artifacts current alongside the work.