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

September 24, 2026 ·

<!-- -->

5 min read

[NGPilot](https://ngpilot.com)

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](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-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[​](#why-a-board-needs-a-diagram-spec "Direct link to 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[​](#copy-paste-1-the-teams-board-as-kanban "Direct link to 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](/assets/images/kanban-2c315769a6fbbe1e595940f425b83b96.svg)

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[​](#copy-paste-2-the-workflows-law-as-a-state-diagram "Direct link to 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](/assets/images/statediagram-v2-20145593c5f7b8a1daffd5b2ff23eb0f.svg)

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[​](#copy-paste-3-wip-limits-and-the-review-gate "Direct link to 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](/assets/images/kanban-2-42b76af115cba279df6974836c7aa407.svg)

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[​](#board-and-rulebook-on-one-page "Direct link to 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](/blog/mermaid-roadmap-prioritization-charts-confluence.md) and the **process handoffs** between the team and others as [swimlanes](/blog/mermaid-process-flow-swimlane-diagram-confluence.md).

## FAQ[​](#faq "Direct link to 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](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-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](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence)

## Related guides

* [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md)
* [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md)
* [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md)
* [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md)
* [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md)

Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links)

**Tags:**

* [confluence](/blog/tags/confluence.md)
* [mermaid](/blog/tags/mermaid.md)
* [kanban](/blog/tags/kanban.md)
* [workflow](/blog/tags/workflow.md)
* [state-diagram](/blog/tags/state-diagram.md)
* [agile](/blog/tags/agile.md)
* [how-to](/blog/tags/how-to.md)