Skip to main content

Kanban Board Diagrams in Confluence with Mermaid (Copy-Paste)

· 5 min read
NGPilot

The sprint board on the wall shows 40 items in "In Progress" and the rulebook says "we limit WIP" and nobody agrees on what the limit is. The board is honest; the documentation is aspirational. A Kanban diagram in the wiki is the board as a spec — columns, limits, and the rework paths drawn so the workflow is a claim the team can argue with.

Quick answer: document the team's board in Confluence as a Mermaid kanban, rendered by Mermaid Plus for Confluence. Columns as headings, work items as indented cards; the workflow rules (who may move what, when, including rework) as a stateDiagram on the same page. This post gives you three copy-paste examples.

Why a board needs a diagram spec​

Jira already is a board — the diagram earns its place when it documents the rules the board encodes:

  • The columns are a promise. A diagram that shows "To Do → In Progress → Done" says how the team claims work flows; the real board either agrees or exposes drift.
  • The WIP limit is a number. Written on the column, the limit becomes reviewable — the diagram is the policy the wall occasionally breaks.
  • The rework path is the honesty. Every workflow has a "back to In Progress" move; drawn, it stops the diagram from being pure happy-path fiction.

The kanban draws state; the state diagram draws the law. Both are text, so both update in the retro that changes the rule.

Copy-paste 1: the team's board as kanban​

Columns first, then cards indented under them. Keep it to the states the work actually visits:

kanban
  To Do
    Payload migration
    Billing webhook
    Rate limiter
  In Progress
    Auth refresh [owner: Maya]
  In Review
    Audit log
  Done
    Healthcheck endpoint
    Helm chart

Rendered Mermaid diagram

The diagram is the board frozen as a spec: five states, six cards, one in flight. Keep the card list short — the value is documenting what the columns mean and where the work binds, not mirroring every Jira issue.

Copy-paste 2: the workflow's law as a state diagram​

The board is the snapshot; the state diagram is the rulebook — every transition, including the ones the happy-path diagram hides:

stateDiagram-v2
  [*] --> ToDo
  ToDo --> InProgress: start
  InProgress --> InReview: submit
  InReview --> InProgress: rework
  InReview --> Done: approved
  InProgress --> ToDo: unblocked
  InProgress --> Done: direct merge
  Done --> [*]

Rendered Mermaid diagram

Read the edges that cross "leftward": InReview → InProgress: rework and InProgress → ToDo: unblocked — the reality of a board. The state diagram makes the workflow enforceable-looking: reviews can check whether the drawn transitions match the configured workflow, and the WIP debate starts from a shared picture.

Copy-paste 3: WIP limits and the review gate​

Put the limit in the heading and draw the gate as a decision between two states. This is the board for the stricter workflow — code review as a real gate:

kanban
  To Do (WIP 5)
    Card A
    Card B
    Card C
  In Progress (WIP 3)
    Card D
  In Review (WIP 2)
    Card E
  Done
    Card F

Rendered Mermaid diagram

The WIP limit lives in the column heading, so the policy is visible in the diagram, not implied. This is the version to pin on the planning room wall and the wiki's team page — it documents the limits the board is supposed to enforce.

Board and rulebook on one page​

The pair works like requirements and their coverage:

  • Kanban = the snapshot. What sits where, right now, labelled by owner.
  • State diagram = the transitions. Which moves are allowed, in both directions, with their guards.

Keep both next to the sprint workflow guide and the delivery timeline of the same work, and update them in the retro that changes a limit. A board's rulebook belongs to the whole team; text in Confluence is how it stays owned.

The workflow diagrams' siblings are on the wiki: the quarter schedule of the same work as a Gantt roadmap and the process handoffs between the team and others as swimlanes.

FAQ​

Does Confluence have a built-in Kanban diagram tool? No — Confluence has no native board diagramming. Mermaid Plus for Confluence renders kanban and stateDiagram-v2 from editable text with a live preview.

Kanban diagram or state diagram for a workflow? Kanban for the board snapshot (columns + cards + WIP); state diagram for the transition rules (guards + rework paths). Keep both; the board is now, the state diagram is the law.

How do I show a WIP limit in a Mermaid Kanban? Write it into the column heading — In Progress (WIP 3) — so the limit is part of the diagram's visible spec.

How do I draw rework in a workflow diagram? Add the reverse transition explicitly (InReview --> InProgress) as a state-diagram edge. The drawn rework path is what keeps the diagram honest.

Render every Mermaid diagram type — kanban, state, gantt, flowchart, swimlane and 24 more — in Mermaid Plus for Confluence, free for up to 10 users.

Try Mermaid Plus for Confluence

All 29 Mermaid diagram types with live preview and one-click templates — free for up to 10 users.

Get it on the Atlassian Marketplace

Related guides