We just went through this cycle for Mermaid diagram apps — one major vendor just announced the end of life of its Connect-based app in January 2027 — and the experience taught us a lot about the real cost of macro migration. Not the license cost. The content cost. This post is that breakdown; the Mermaid story is the case study at the end.

The anatomy: what a macro actually leaves behind​

Confluence macros are stored inside the page itself. The app renders them live; Confluence only stores a small block describing the macro and its content. When the rendering app disappears, the page keeps the block but nothing draws it anymore. The text, the diagram definition, the table — whatever the app put in storage — is still there.

So content usually survives the app. What dies is the render. And that is the trap: "my pages still exist" feels safe until you open one and the diagram simply is not there anymore.

Whether the surviving data is usable depends entirely on the vendor:

• Some apps keep the human-readable source (Mermaid syntax, markdown) directly in storage
• Some wrap it in JSON with revision history
• Some store only a rendered image and keep the source in a proprietary attachment format
• Some do all three, depending on the app version that last touched the macro

Every one of those is a different migration project.

Why the cost is always higher than it looks​

Cost 1: the formats. Each vendor's storage format is undocumented and versioned. Reading "what's on the page" is not a query — it is a small reverse-engineering project per app, sometimes per app version. This is the single biggest line item in any macro migration.

Cost 2: the scale is invisible until you measure it. Teams consistently underestimate how many pages depend on an app, because diagrams are scattered — one here in an architecture doc, three there in a runbook. Nobody costs a migration they have not inventoried.

Cost 3: the app ecosystem keeps generating this problem. This is not a rare event. Atlassian ended its own Server product line in 2024, forcing one of the largest app-and-content migrations in the platform's history. Vendors retire or pivot — the Connect-based Mermaid app by Stratus reaches end of life in January 2027, the very case that prompted this post. Free first-party alternatives keep appearing in the same categories. And independent of any retirement, teams switch vendors — which is the same migration with a different trigger. If your team uses Confluence deeply today, the odds that it will face at least one macro migration in the next few years are close to certain.

Cost 4: the manual fallback is real but doesn't scale. Opening every page and recreating content by hand genuinely works — for ten pages. At a hundred, triage paralysis sets in: nobody costs it, nobody schedules it, and the migration quietly becomes "we'll deal with it when it breaks."

Case study: what migrating Mermaid diagrams took​

When the retirement news landed, we built migration support into our Mermaid app — and the economics matched the framework above almost exactly.

Inventory first. A scan reads page storage and counts macros per page. Teams that ran it found diagrams in spaces nobody expected — the invisible-scale problem, confirmed every time.

Four vendors, four formats. We ended up supporting four distinct storage layouts: source in a macro parameter, source in a JSON blob in the macro body, source in a companion code block, and a renderer macro that references all of the above. Four parsers, each a small reverse-engineering project against undocumented formats.

Conversion is text processing; judgment is not. Replacing an old macro with a new rendered diagram at the same position in the page is mechanical. The hard parts were elsewhere: pages that mix several vendors' macros (convert only what you scanned for?), diagrams whose source cannot be extracted (report them honestly, per page, or they vanish without a trace), and the rollback story (in-place conversion plus page history beats any backup script).

The result: a space sweep per source app, a review table before anything is written, and every conversion landing as a normal page version. That combination turned an unbounded, scary project into a bounded checklist.

The general checklist​

Whatever the macro type — diagrams, markdown, tables, whiteboards — the same checklist applies:

1. Inventory by scanning page storage, not by asking around
2. Map the formats: where each vendor keeps the source, and whether it is human-readable
3. Migrate one vendor at a time, with per-page results before anything is written
4. Convert in place and let page history be the rollback mechanism
5. Report failures per page — silent skips are how content quietly dies anyway

The teams that skip steps 1 and 2 are the teams whose migration "unexpectedly" takes a quarter.

If the macros you're leaving behind are Mermaid diagrams, you can start today: Mermaid Plus Diagrams & AI Agent for Confluence includes the migration wizard described above — it recognizes macros from Mermaid Chart, Stratus, the Atlassian Labs viewer, weweave and Tech Labs, and converts them in place. The migration guide walks through every step.

If you're switching away from a different macro type — draw.io, Excalidraw, markdown, tables — the checklist above still applies, and the same pipeline (inventory → parse → convert in place) is how we're expanding coverage: Excalidraw is next on the roadmap. Tell us which app you're switching from — the more we know about the formats teams are actually leaving, the faster that list grows.

And if you're mid-decision right now, bring it to the Community discussion — the "we'll migrate as we go" plan needs all the reality checks it can get.

Quick answer: Jira has no native checklist object, so there is nothing native to template. Paste one of the checklists below into an issue, install Checklist Workflow Automation for Jira (free for up to 10 users) to turn it into a real checklist, flag the non-negotiables as required, and save it via the ⋯ menu as a reusable project template. Add the Checklist required items complete validator to the Done transition and the template stops being a suggestion.

Where a checklist template can live​

Three storage spots, in increasing order of usefulness:

1. A Confluence page or Slack message — the "master copy" nobody opens at ticket time. Fine as documentation, useless as automation.
2. The issue description — works, and pairs with issue templates that pre-fill the description on every new issue. But checkboxes in free text are inert: nothing tracks their state, and nothing stops the issue closing unchecked.
3. A saved checklist template on the issue itself — with Checklist Workflow Automation, a saved template re-applies as live checklist items with state, required flags, and JQL visibility. Sub-task nesting round-trips too, and CSV import/export means you can maintain the master list in Excel and paste it in.

The rest of this post gives you the lists. Storage spot 3 is what makes them stick.

The six templates​

Each list is plain markdown — paste it as-is, then flag the ⭐ items as required.

1. Bug fix​

- ⭐ Reproduce the bug on the affected version
- ⭐ Write a failing test that captures the bug
- Fix implemented
- Regression test added for the surrounding area
- ⭐ Changelog / release note entry written
- Reporter confirmed the fix (or QA sign-off)

The discipline point is the first item: a fix that cannot be reproduced cannot be verified. Pair the list with a structured bug template so the reproduction steps arrive with the ticket.

2. Incident response​

- ⭐ Severity assessed and incident channel opened
- Customers / stakeholders notified (status page or banner)
- ⭐ Mitigation in place — impact stopped or contained
- Timeline of events recorded as it happens
- Root cause identified
- Postmortem document created and scheduled
- Follow-up actions filed as issues

Items 1–3 are the ones that get skipped at 3 a.m. — which is exactly why they are the required ones. The validator refusing to close the incident until the status page was updated is cheaper than the retro conversation about why it wasn't.

3. Release​

- ⭐ All release-scope issues resolved or explicitly deferred
- ⭐ Test pass complete on the release candidate
- Release notes drafted and reviewed
- Documentation updated
- ⭐ Deployed to production
- Smoke test on production passed
- Announce to stakeholders

This is the definition-of-done pattern scaled up from one issue to a version. Keep the issue-level list short and let the release checklist own the version-level gates.

4. Code review​

- ⭐ Tests cover the changed behavior
- No new warnings or lint suppressions
- Error paths handled, not just the happy path
- Security-sensitive input validated
- ⭐ Approver is not the author

Short on purpose — a review checklist longer than this gets skimmed. The last item enforces a policy that Jira alone won't.

5. Onboarding​

- ⭐ Accounts and access provisioned
- Development environment set up and first build runs
- ⭐ Welcome buddy assigned
- First issue assigned and completed
- 30-day check-in scheduled

Onboarding is where checklist templates pay off fastest: the process runs a few times a year, so nobody carries it in their head, and the person who wrote it has often already left the team.

6. Content publishing​

- ⭐ Draft reviewed and approved
- SEO title and meta description within limits
- Images checked (alt text, sizing, rights)
- ⭐ Published and links verified
- Distribution done (newsletter, social, community)

For teams that run Jira beyond engineering — marketing, ops, HR — this is the proof that the same enforcement pattern works on any repeatable list.

Make the template automatic where it matters​

Two layers of "automatic", both worth wiring:

• The list arrives on its own. Saved checklist templates apply from the ⋯ menu in one click; for fully automatic pre-fill, put the checklist in an issue template's description so the list is there the moment the issue is created — no click at all.
• Done waits for the list. The 'Checklist required items complete' validator on the Done transition is what turns a template from a reminder into a rule. This is the part Jira cannot do natively at any price — the full enforcement walkthrough is here.

Once the checklists are live, they are searchable: issue in hasIncompleteRequired() finds every issue still owed work before Done — a saved filter that answers "what's blocking release?" without opening a ticket.

Related Resources​

• Jira Checklists: Block Transitions Until Done — the enforcement mechanics in depth: panels, required flags, the validator, and JQL
• Jira Definition of Done: Template + How to Enforce It — the one checklist every issue type should have
• Create Jira issue templates — pre-fill the whole issue body, checklist included, on every new ticket
• Checklist Workflow Automation for Jira — templates, CSV import/export, enforcement, and the audit log

Quick answer: Effective October 13, 2026, Atlassian raised Cloud list prices — Jira and Confluence Standard/Premium +7–10%, Enterprise +8%; JSM (Service Collection) +7.5–10%; Bitbucket Premium +10%; Jira Product Discovery +5%; Guard +3–5%; Atlassian Government Cloud +5–10% by product. It applies to new purchases, upgrades and renewals from that date, and it's the third consecutive annual increase (official page, Adaptavist's breakdown). NGPILOT's response: zero changes across all 36 of our Marketplace apps. Free for up to 10 users stays free.

What changed, product by product​

Announced in late August 2026, effective October 13, 2026 — new purchases, upgrades and renewals from that date onward. Existing subscriptions keep their current price until their next renewal falls due.

Atlassian Government Cloud: Jira +8% · Confluence +8% · Service Collection/JSM +10% · Guard +5%.

Atlassian's stated reason is continued investment in AI (Rovo), the Teamwork Graph, integrated workflows, and enterprise capabilities. Worth naming the pattern too, because renewal budgets care about trajectories more than single years: this is the third consecutive annual Cloud increase since 2024, and it sits on top of a separate 15% Data Center increase that took effect in February 2026.

What you can actually do about it​

• Check when your renewal lands. The increase applies at renewal, so a subscription renewing in October pays it immediately; one renewing in August 2027 pays it then. There's nothing to game here — just don't let the renewal surprise the budget owner.
• Audit your user tiers before renewing. A +7–10% list-price increase is a fine moment to notice you're paying Premium for 12 users who left in March. Tier hygiene is the one lever that's fully yours.
• Watch the collection bundling. The increases differ by collection (Service Collection's Enterprise tier is +10% while Teamwork's is +8%) — if you pay for collections, the math of what's bundled vs à la carte changed.

Our position: we're not raising prices​

Every NGPILOT app keeps its current pricing through this — all 36 of them, Jira and Confluence alike. Concretely:

• The free tier stays. Every one of our apps is free for up to 10 users. That's not a promo ending in November; it's the product.
• No increase at your next renewal. Nothing on our Marketplace listings changed on October 13, and nothing is scheduled to change at any renewal date.
• Why we can hold: our apps are Forge-native — no Data Center legacy codebase to amortize, no server-infrastructure costs passing through to you. When the platform's costs move, ours don't move with them.
• And why we'd hold anyway: a price increase landing in the same budget line as your Atlassian renewal compounds the exact pain it comes out of. Your platform bill going up shouldn't drag your app stack up with it. Pricing stability is the deal, and this is the quarter where saying so out loud matters.

If an Atlassian price line is what brought you here: browse the NGPILOT app catalog — diagramming (Mermaid Plus, Excalidraw Plus), Markdown and formatting, code blocks, checklists, banners, import/export — free for up to 10 users on every one, paid tiers that don't move out from under you.

Sources​

• Atlassian — Future Pricing (official price update page)
• Atlassian Cloud price updates, effective October 2026 — Adaptavist — published 28 August 2026, updated 2 September 2026; the per-product table above follows their breakdown
• Atlassian Cloud Price Increase 2026 — Empyra — effective date, renewal semantics, and the annual-increase pattern

Quick answer: For one page, copy-paste through a converter. For anything real — a space, a corpus, an LLM knowledge base — use Modern Importer & Exporter for Confluence: select pages or whole spaces, choose Markdown (plus any sibling formats in one ZIP), and get clean .md files with images bundled and a manifest listing everything exported.

Method 1 — Copy-Paste Through a Converter​

Open the page, copy the content, paste it into any HTML-to-Markdown converter or your editor's paste-as-Markdown.

Good for: one page, once — a doc you're moving into a README today.

What's missing: structure under scale. Tables mangle, macros vanish or arrive as HTML fragments, images break (they point at your Confluence instance, which the reader — or the model — can't access), and nobody is doing this four hundred times. It's a bridge, not a pipeline.

Method 2 — HTML Export + a Conversion Step​

Confluence's native space export includes HTML. Convert the HTML bundle to Markdown with a tool (Pandoc is the standard), post-process the leftovers.

Good for: one-off migrations where you already own a conversion script.

What's missing: two conversion layers, each with its own losses. Confluence's HTML export is built for archival (it carries its own CSS, navigation and storage-format quirks), so the Markdown that emerges needs real cleanup — and images still need re-linking. It works; it's just a project.

Method 3 — Export Markdown Directly​

Modern Importer & Exporter for Confluence exports Confluence content as Markdown natively — no intermediate format:

1. Open Apps → Modern Importer & Exporter, or right-click a page for a single export.
2. Select the pages or spaces you want.
3. Choose Markdown — or bundle Word, HTML, JSON, XML in the same ZIP if the migration needs siblings.
4. Export: images are downloaded and included, files are organized by space, and a manifest lists every page that came out.

The last two details are the ones that decide whether the output is usable. Images in the bundle means the Markdown references files that actually exist next to it — not https://your-instance.atlassian.net/wiki/download/... URLs that 404 outside Confluence. And the manifest is what turns "a folder of files" into a corpus: your RAG ingestion or docs repo can walk the manifest, know what each file is, and detect gaps.

Making the Output LLM-Ready​

If the destination is a model rather than a human, the export is step one:

• Chunk along the headings. Markdown's #/## structure is what chunkers want — no HTML-stripping step means no boilerplate baked into every chunk.
• Ship the manifest with the corpus. Page titles, spaces and timestamps let retrieval cite sources and let you re-export only what changed.
• Keep code fences. Markdown export preserves fenced code blocks, which is the difference between a model that can quote your API example and one that quotes mangled indentation.
• Re-export per sync, not per crisis. Because the exporter runs the same selection every time, refreshing the corpus is a two-minute task — schedule it like a backup.

For the other half of the pipeline — chunking, embedding, retrieval patterns on Confluence content — see RAG with Confluence: Build an AI Knowledge Base.

Which Method Should You Use?​

Related Resources​

• Markdown to Confluence: 3 Ways to Convert and Paste — the reverse direction, into Confluence
• RAG with Confluence: Build an AI Knowledge Base — what to do with the corpus once you have it
• How to Migrate Confluence Content — when the goal is moving, not converting
• Modern Importer & Exporter for Confluence — full documentation: formats, wizard, import side

Quick answer: For a comment, use Jira's code snippet block with JSON as the language — monospace, indentation preserved. To format, run it through jq or your editor and paste the result back. To format, validate and explore JSON without leaving the issue, JSON Graph Viewer & Visualizer for Jira adds a Paste JSON tab that highlights and validates as you type, plus a node graph of the payload's shape.

Method 1 — the Native Code Block (the Floor)​

Every method starts here. In the comment or description editor, insert a code snippet (the {} icon or typing /code), paste the payload, and pick JSON as the language.

What you get: monospace text that keeps its line structure and copies cleanly back out — which is the entire difference between readable and unreadable JSON.

What you don't get: a pretty-print button (a minified one-liner stays a minified one-liner), syntax validation (a stray comma ships silently), or any way to collapse the 200 lines you don't care about. The code block is storage, not tooling.

Method 2 — Format Outside, Paste Back (Free, Works Everywhere)​

When the payload arrives minified, format it before it enters Jira:

# jq — one line, any payload you can curl
curl -s https://api.example.com/orders/42 | jq .

# or format what's already on your clipboard
pbpaste | jq .

Any editor does the same (VS Code: format document with JSON language mode). Paste the formatted result into the Method 1 code block.

The round-trip is the cost: for a one-off share it's ten seconds, and it keeps Jira clean of extra apps. As a daily workflow — debug a webhook, share a payload, review an integration — it breaks down, because the formatted copy in the comment is stale the moment the API response changes.

Method 3 — an In-Issue Panel That Formats, Validates and Graphs​

JSON Graph Viewer & Visualizer for Jira puts the tooling where the JSON actually lives — the issue. It's read-only (nothing it sees can be changed, and rendering happens in your browser), and there's nothing to configure.

Paste JSON is the tab for the comment-and-webhook workflow: a syntax-highlighted editor that renders as you type. Paste a dev-tools response, a webhook payload or an API example; invalid input gets told to you plainly — "That isn't valid JSON. Check the syntax and try again." — instead of a blank panel. Valid JSON becomes an interactive node graph: expand and collapse objects, fold a 200-element array into a single n items node, pan and zoom to see the shape you'd otherwise count braces for.

The panel also finds JSON that's already on the issue, which is the part pasting can't do:

• Issue fields — any field whose content parses as JSON (a REST payload stored in a custom field) renders automatically; several matches get a picker.
• Issue properties — JSON that other apps stash on the issue as entity properties (integration state, cached API data) shows up under its own tab.

A view-mode dropdown switches between Code (formatted and highlighted), Graph, or both side by side — read the payload above, see its shape below.

Where JSON Hides in Jira​

The last three are the reason "format outside and paste back" stops scaling: the JSON isn't text someone pasted once — it's state that changes, and a stale formatted copy in a comment is worse than none.

Which Method Should You Use?​

Related Resources​

• How to View JSON in Jira — the three JSON sources in depth
• JSON Graph Viewer & Visualizer for Jira — full documentation: sources, view modes, themes

Quick answer: Every example below follows the same three-part pattern — what, when, what to do — and stays under 200 characters. Copy the message for your scenario, fill in your dates and links, and pick persistent vs dismissible from the settings matrix. Jira banners render plain text only (emojis work), so the wording does all the work.

Scheduled Maintenance​

Advance notice (a week out, persistent):

🔧 Scheduled maintenance: Jira will be unavailable Saturday, June 14, 2–4 AM EST. Plan your work around the window.

Day-of countdown (persistent):

🔧 Jira goes offline in 2 hours for scheduled maintenance (2–4 AM EST). Save your work. Full service back by 4 AM.

Window closed (dismissible):

✅ Maintenance complete — Jira is back. If anything looks off, ping #it-help with a screenshot.

Production Incident​

Active incident (persistent):

⚠️ Production incident in progress: API latency is elevated. Status updates every 30 min in #incident-response. No action needed from you.

Incident with user action (persistent):

⚠️ Do not deploy to staging — a broken build is circulating. Incident in progress, updates in #incident-response.

All clear (dismissible):

✅ Resolved: API latency back to normal as of 14:20 UTC. Root-cause write-up coming in the postmortem doc.

Policy Changes​

New requirement (dismissible):

📋 New policy from Monday, Feb 1: every bug must include reproduction steps. Details and examples: wiki.acme.co/bug-policy

Deadlines​

Quarter close (dismissible):

📅 Timesheets for Q1 are due Friday, Jan 20 at 5 PM. Missing entries block invoicing. Submit: timesheets.acme.co

Code freeze (persistent during freeze):

❄️ Code freeze in effect until the 3.2 release ships Thursday. Bug fixes only — release captain approval for exceptions.

Security​

Advisory (persistent):

🔒 Security advisory: phishing emails are targeting Jira accounts. We never ask for your password. Verify sender before clicking: wiki.acme.co/security

Credential rotation (persistent during the window):

🔒 Rotate your password by Friday — forced reset at 6 PM. Takes 2 minutes: id.acme.co/rotate. Questions: #security

Onboarding & Team Changes​

Welcome (dismissible):

👋 New to the team? Start here: onboarding checklist, tool access requests and who-to-ask are in Confluence: wiki.acme.co/start

Reorg announcement (dismissible):

📣 From March 1, the Payments team joins Platform. Escalations for payment bugs go to @platform-oncall. Org chart: wiki.acme.co/org

Releases & Deployments​

Release note (dismissible):

🚀 3.1 is live: bulk issue editing, saved filters, dark mode. Release notes with screenshots: wiki.acme.co/3-1

Deployment window (persistent during):

🚀 Deploying 3.2 to production now (est. 20 min). Expect brief slowdowns. Do not run migrations until the all-clear.

Events & Rituals​

Office closure (dismissible):

🏢 Office closed Monday, May 29 (public holiday). Jira coverage is best-effort — non-urgent issues will be triaged Tuesday.

Survey round (dismissible):

📝 Platform survey closes Friday — 5 minutes, anonymous, results shared with everyone. Take it: survey.acme.co

Training session (dismissible):

🎓 Jira automation workshop this Thursday 3 PM — bring a repetitive task, leave with it automated. Signup: wiki.acme.co/workshops

Migrations & Moves​

Server-to-Cloud migration (persistent during):

📦 Jira migrates to Cloud this weekend. Read-only from Friday 6 PM, back Monday 8 AM. Export what you need: wiki.acme.co/migration

Compliance freeze (persistent during):

🔒 Audit period Mar 1–15: no permission changes and no project deletions without compliance sign-off. Questions: #compliance

The Settings Matrix​

For each scenario, the banner behavior that matches the message (Jira's native banner has a single global on/off — the dismissible/persistent and visibility controls below are what Modern Announcement Banner for Jira adds on top):

Two rules the matrix encodes: acknowledge-once messages get dismissed; in-progress situations persist. And every banner gets a retirement date — a stale banner is ad blindness training for your whole instance.

Wording Rules (Why These Examples Look Like This)​

1. What, when, what to do — in that order. Users scan the first seven words; lead with the event, not the pleasantries.
2. One message per banner. Jira shows a single banner, so a second topic makes the first unreadable. Modern Announcement Banner still shows one banner at a time — it just keeps the library ready to switch.
3. Specific beats urgent. "URGENT" without a date is noise; "offline Saturday 2–4 AM EST" is information.
4. Emojis are your only formatting. Banners render plain text, so ⚠️ 🔒 📅 do the visual work a bold tag can't. One per banner — they're punctuation, not confetti.
5. Give the URL a name. "See wiki.acme.co/bug-policy" beats "see the wiki" — plain-text URLs get copy-pasted, vague pointers get ignored.

Related Resources​

• Jira Announcement Banner Customization — FAQ — formatting limits, scheduling, targeting
• Set Up Announcement Banners in Jira — native banner vs app, step by step
• How to Set Up Announcement Banners in Confluence and Jira — both products side by side
• Modern Announcement Banner for Jira — saved library, dismissible banners, public/private visibility

Sources​

• Announcement banner REST API — Atlassian Developers — the native banner's update endpoint takes a message string only: no format field, and HTML in the message renders as raw text

Quick answer: A definition of done (DoD) is the team-wide checklist every issue satisfies before closing — distinct from per-story acceptance criteria. Jira has no native DoD field, so the setup that works is: keep the DoD as a checklist template applied to every new issue, flag the non-negotiables as required, and add a workflow validator (Checklist Workflow Automation for Jira, free up to 10 users) that blocks the Done transition while any required item is unfinished. Below: the template, the storage options, and the enforcement ladder.

The Template​

Definition of Done — user story​

Code peer-reviewed
Unit + integration tests pass in CI
Acceptance criteria demonstrated to the reporter
No new high/critical vulnerabilities
Documentation and release notes updated
Feature flag / rollout plan confirmed
Stakeholders notified

Mark the first two and the release-notes line required — they are the ones teams skip under deadline pressure, and the ones that cost the most when skipped. The rest stay optional: nothing destroys a definition of done faster than twenty mandatory checkboxes nobody reads.

Definition of Done — bug fix​

Root cause identified (not just the symptom)
Fix verified in a production-like environment
Regression test added
Release notes / affected users updated
Related issues linked

Bugs need a different gate than stories — a defect closed without a regression test is a defect scheduled to return. Same project, second template, so "done" stays one auditable concept with two shapes.

What the template is not​

Not a checklist of who does what (that's assignment) and not a list of what this story must do (that's acceptance criteria — keep those in the story's own description). The DoD is only the conditions that are true for every piece of finished work. If you're writing an item that applies to some tickets only, it belongs in acceptance criteria.

Where to Store It (So People Actually See It)​

The wiki page is where definitions of done go to die. The description template is one step better — Modern Issue Templates for Jira pre-loads a rich-text body (description, DoD section, testing notes) on every new issue automatically, so the checklist is at least present on birth. But presence is not enforcement: a text checklist in the description can be deleted by anyone, and nothing stops the transition.

The Enforcement Ladder​

Level 0 — nothing. The default. Close the ticket, hope for the best.

Level 1 — present. The DoD template auto-applies to every new issue (issue template). Reviewers see it; nothing enforces it.

Level 2 — enforced. The checklist lives on the issue, the non-negotiables are required, and a validator blocks Done until they're done.

Level 2 is the whole point, and it needs one workflow edit with Checklist Workflow Automation for Jira:

1. A Jira admin opens Project settings → Workflows, edits the workflow, and on the transition into Done adds the validator Checklist required items complete (category: Forge apps).

2. From then on, closing an issue with an unfinished required item is refused, and Jira names the offenders:

   Complete required checklist items before transitioning: "Code peer-reviewed", …

3. Optional: add the Complete required checklist items post function to the same transition if your DoD documents review steps rather than work — it completes the required items automatically once the reviewer decides to move on.

Two rules make the gate predictable: only exactly Done satisfies a requirement (a custom status like Waiting on vendor still blocks, Skipped never counts), and the validator fails open — if the app can't read a checklist, the transition goes through rather than bricking the workflow.

Audit What Slips Through​

Enforcement prevents new shortcuts; the JQL layer catches everything already in flight:

issue in hasIncompleteRequired()
cwaIncompleteRequired > 0 AND sprint in openSprints()
cwaOverdueRequired > 0

Save the first as a filter called "Owed before Done" and pin it as a dashboard gadget — it's the team's honest backlog of unfinished endings. Pair it with overdue reminders, which comment on issues where a required item has blown past its due date and mention the assignee (at most once every 7 days per issue, so it nudges without nagging).

Do You Need an App for This?​

For Level 1 — no. Any issue-template mechanism puts the DoD text on tickets.

For Level 2 — yes, something has to count checklist state inside a workflow validator, and native Jira can't. The honest landscape: ScriptRunner can script the same gate if you already pay for it; HeroCoders' checklist app covers this ground; Checklist Workflow Automation does it without scripts and stays free up to 10 users, with the JQL functions, CSV round-trip and reminders built around the same required-item concept. Pick by what you need around the gate, not the gate itself — every option blocks the transition.

Related Resources​

• How to Add a Checklist to Jira — the checklist mechanics in depth: panels, required flags, JQL and templates
• Jira Checklist Templates: Copy-Paste Sets for 6 Workflows — scenario checklists (bug fix, incident, release, review, onboarding) beyond the DoD
• Create Jira Issue Templates — put the DoD body on every ticket from birth
• Plan Jira Sprints That Actually Work — where the DoD gate sits in sprint planning
• Checklist Workflow Automation for Jira — full documentation: enforcement, templates, CSV, JQL, audit log

Sources​

• Manage workflow transitions — Atlassian Support — validators and conditions on transitions
• Jira workflow conditions — what native conditions can and can't check — the boundary that makes checklist validators necessary

Quick answer: Mermaid 12.2 adds mindmap.colorBy: depth — opt-in mind map coloring where each hierarchy level pulls from the theme palette — plus fixes for circle node sizing, mind map labels, and swimlane rendering (including the fix that stops two diagrams on one page from colliding). In Enhanced Markdown for Confluence, Mermaid Plus Diagrams & AI Agent for Confluence, and Mermaid Plus Diagrams for Jira, add the config block to any mermaid fence or diagram panel. Existing diagrams render unchanged.

The headliner: mindmap.colorBy: depth​

Mind maps encode hierarchy, but by default every node wears the same palette role — the structure lives only in the lines. With 12.2 you opt in once:

---
config:
  mindmap:
    colorBy: depth
---
mindmap
  root((Platform))
    Billing
      Invoices
      Dunning
    Identity
      SSO
      SCIM
    Observability
      Traces
      Alerts

Every level takes its color from the theme palette the diagram already uses — root, first-level branches, and leaves become visually distinct bands with zero per-node styling. No classDef lines, no manual colors to keep in sync when the hierarchy changes; the color is the depth.

Two details worth knowing:

• It's opt-in. Without colorBy: depth, mind maps render exactly as they did in 12.0 and 12.1 — no existing diagram changes appearance.
• It reuses the theme palette. Dark mode, custom themes, the neo look — the depth colors come from whatever theme is already active, so the map stays consistent with the rest of the page.

The quiet fix that matters most on Confluence​

The easiest one to scroll past in a changelog: swimlane cluster DOM ids are now scoped per diagram (#8161). Before, two diagrams on the same page could collide on an internal id — and Confluence pages are exactly where that happens: a runbook with a flowchart and a swimlane, a design doc with three diagrams stacked.

Also in the swimlane batch: edges that detour around a lane no longer share an attachment point with their neighbor (#8383), lane title bands stay clear of crossing edges (#8384), and nodes with no edges keep their source order instead of being sorted by id (#8366) — so a hand-ordered incident runbook lane renders in the order you wrote it.

The rest of 12.2​

All of it is fix-grade: syntax unchanged, behavior corrected. If a diagram looked slightly wrong in 12.1 — a label off-center, a lane band under an edge — 12.2 is the "try again" release.

Related Resources​

• Mermaid 12 in Confluence & Jira — the 12.0 release: use case diagrams, ELK default, new look
• Mind Maps & Hierarchy Diagrams in Confluence — the mind map syntax this coloring upgrades
• Swimlane Process Diagrams in Confluence — the diagram type that got the most fixes in 12.2

Sources​

• mermaid@12.2.0 release notes — mermaid-js/mermaid on GitHub, published 2026-10-13

Quick answer: Confluence has no native OpenAPI rendering — a code block is your floor. For interactive docs, install Modern OpenAPI (Swagger) Integration for Confluence, insert its macro, paste an OpenAPI 3.x / Swagger 2.x spec (YAML or JSON), and save: the page gets validated, navigable API documentation with expandable endpoints, request/response examples and example/schema model views, in the reader's own theme.

Method 1 — Code Block (the Floor)​

Paste the spec into a code snippet block, language YAML or JSON.

Good for: "can you check this spec" reviews between two engineers.

What's missing: everything after the paste. No navigation (find /orders/{id} by scrolling), no examples rendered from the schema, no validation until a human reads it, and a 3,000-line spec makes the page unusable for everyone who isn't actively editing it.

Method 2 — Link Out to a Renderer​

Park the spec in a repo and link to Swagger Editor, Redoc, or a hosted docs portal.

Good for: teams whose real docs already live outside Confluence.

What's missing: the page stops being documentation and becomes a redirect. Reviewers leave Confluence to answer questions; the page can't show the one endpoint being discussed; and access control is now someone else's problem — the spec URL is visible to anyone with the link, while the Confluence page respected permissions.

Method 3 — the Macro (Interactive Docs on the Page)​

Modern OpenAPI (Swagger) Integration for Confluence renders the spec inside the page:

1. Insert the macro (/ → search for its name). The config panel has a code editor on the left.
2. Paste the spec — OpenAPI 3.x or Swagger 2.x, YAML or JSON. Click Format to auto-indent.
3. Validation runs as you type: a green badge confirms the spec parses; a red badge names the problem before it ever reaches readers.
4. Configure the reader experience and Save.

What readers get on the page:

• Expand and collapse — endpoints grouped by tag, open only what you're discussing.
• Request and response examples rendered per operation, not hand-derived from the schema.
• Models as Example or Schema — flip between sample values and type structure with a dropdown.
• Tag filter — a search box over tag names for large APIs (it matches tags like pet or store, not endpoint paths — so tag your operations meaningfully).
• Theme-matched — follows each reader's Confluence light/dark setting.

Tips for Large Specs​

• Start small. Paste a two-endpoint spec first, verify the render, then paste the full one — debugging a 5,000-line paste is worse than debugging ten lines.
• Tag deliberately. The tag filter and the default Tags expansion both key off your spec's tags; a spec with no tags opens as one undifferentiated list.
• Expansion = None for reference pages. Internal platforms pasting a whole API set should load collapsed; the reader opens the section they came for.
• Split by domain at 1024 KB. The macro's raw size ceiling is generous, but one macro per bounded context (auth, billing, webhooks) beats one mega-page for readers anyway.

Which Method Should You Use?​

Related Resources​

• Code Blocks in Confluence — where Method 1 comes from, and how far proper highlighting goes
• Display JSON, XML and Code in Confluence — the same story for payload formats
• Modern OpenAPI (Swagger) Integration for Confluence — full documentation: options, troubleshooting, limits

Quick answer: Jira is for work that moves — issues that travel through a workflow from To Do to Done. Confluence is for knowledge that stays — pages that hold decisions, specs, and runbooks and get revised as reality changes. They are complements, not competitors, and the link between them is where most teams get the real value.

What Jira is for​

Jira tracks issues — units of work with a type (bug, story, task), a status, an assignee, and a place in a workflow. Its strengths are all downstream of that model:

• Workflow enforcement — work moves through states you define, with rules about who can move what.
• Filtering and reporting — JQL queries over thousands of issues; sprint boards, burndown charts, velocity.
• Accountability — every field change is stamped; you can always answer "who moved this and when."

What Jira is not is a place to write. An issue description holds a paragraph or two fine; a 20-page product spec inside a Jira description is a document nobody can find, link to, or maintain.

What Confluence is for​

Confluence holds pages organized in a space tree. Its strengths are the mirror image:

• Long-form content — a real editor with headings, tables, macros, and diagrams rendered right on the page.
• Organization — spaces, page trees, and labels so knowledge is findable by structure, not just search.
• Institutional memory — page histories and comments make "why did we decide this?" answerable two years later.

What Confluence is not is a tracker. You can build a task list on a page, but pages do not have states, assignees with notification rules, or JQL — a to-do list that has to be worked does not belong there.

The boundary in one table​

When one alone is enough​

• A 5-person team tracking tasks can live in Jira free plan alone — keep the "documentation" in issue descriptions and a pinned link or two, and accept the ceiling.
• A writing-heavy team with no structured work (agency producing content, for example) can run on Confluence alone with page-level task lists.

The trap is the middle: the moment specs start affecting tracked work, or tickets start needing real explanations, gluing a second product onto the first costs less than the workarounds.

Where the two connect​

The integration is the point, not an afterthought:

• Mention an issue key on a page (PROJ-123) and Confluence renders a live card with current status.
• Link issues to pages so the spec, the meeting notes, or the postmortem sits one click from the work it explains.
• Dashboards and macros surface Jira data inside Confluence pages for status pages and leadership reviews.

Where apps make the pair genuinely good​

Both products ship lean, and the Marketplace is where teams close the gaps:

• Making Confluence pages richer — text-native diagrams (see Mermaid in Confluence), custom fonts, code blocks, and structured FAQ or Q&A macros turn a plain wiki into a real knowledge base.
• Getting data out of Jira — Cloud's built-in export is famously limited; a bulk export to Excel/CSV is the standard fix for reporting and audits.
• Bridging the two — issue templates that stamp consistent structure into Jira work, and task lists on Confluence pages that mirror real tracked work, keep the boundary clean instead of letting each product decay into a bad copy of the other.

The NGPILOT app catalog covers both products — every app is free for up to 10 users, and installs directly from the Atlassian Marketplace.

Related guides​

• Jira issue history: who changed what — the audit trail Jira keeps and how to read it
• Bulk download Jira attachments — when the work data has to leave Jira
• Run team knowledge with FAQs and Q&A in Confluence — structuring the knowledge side

Quick answer: there are three working methods in Confluence Cloud. Convert PlantUML into an editable Excalidraw whiteboard with an AI agent (best for diagrams you still maintain), render externally and embed an image (fine for frozen history), or write new diagrams in Mermaid (best for everything you have not created yet). This post shows all three.

Why there is no PlantUML in Confluence Cloud​

PlantUML rendering requires executing the PlantUML engine — a Java process that turns .puml source into SVG. On Data Center, apps bundled that engine server-side. Confluence Cloud's Forge platform does not give apps a Java runtime, so the classic PlantUML macros never made the jump, and Atlassian has no native diagram-as-code feature beyond Mermaid's text syntax in some app ecosystems. That is why searches for PlantUML in the Marketplace often return nothing useful for Cloud.

Method 1: convert PlantUML into an editable whiteboard​

Excalidraw Plus Whiteboards & AI Agent for Confluence ships with a Rovo AI agent that converts PlantUML source into an Excalidraw whiteboard. Open Confluence chat on your page and ask it to convert; the output is fully editable shapes on the canvas — reposition, restyle, and extend them like any drawn whiteboard.

This is the right method for live diagrams — the sequence diagram that changes with every sprint, the component diagram you actually keep updated. Two honest caveats:

• Conversion is one-directional: PlantUML → Excalidraw. (Mermaid converts in both directions; PlantUML does not convert back.)
• Exotic PlantUML constructs may need a touch-up after conversion. The shapes arrive; exotic styling sometimes does not.

Method 2: render externally, embed the picture​

For diagrams that are frozen history — the architecture as it was in 2023, the audit appendix — converting is wasted effort. Render the .puml outside Confluence:

1. Paste the source into the public PlantUML server (plantuml.com/plantuml) or run it through a local plantuml.jar / CI render step.
2. Export PNG (quick) or SVG (crisp at any zoom).
3. Attach the image to the Confluence page.

Zero apps, zero cost, and the diagram looks exactly as it did on Data Center. The trade: it is a picture now. Nobody edits it in place, and search cannot read inside it. If a diagram needs its next revision, that is your signal to use Method 1 or 3 instead.

Method 3: write new diagrams in Mermaid​

For everything you have not written yet, the pragmatic answer is to stop accumulating PlantUML debt. Mermaid covers the everyday UML set — sequence, class, state, ER, activity-style flowcharts — and has first-class Confluence support: Mermaid Plus Diagrams & AI Agent for Confluence renders 30 Mermaid diagram types from a /mermaid macro with live preview, and its AI agent creates and edits diagrams from chat.

The syntax is different from PlantUML, but the mental model is identical: text in, diagram out, versioned with the page. The step-by-step Mermaid guide covers the move in ten minutes.

Which method for which diagram​

Related guides​

• Create Mermaid diagrams in Confluence — the step-by-step editor walkthrough
• Mermaid vs PlantUML vs Graphviz for Confluence — choosing between the three text-to-diagram syntaxes
• Excalidraw AI agent in Confluence — how the conversion and chat editing work

The migration is done. Pages moved, spaces are there, the site is live and people are using it. Then someone clicks a link in an onboarding page and lands on a 404 that points at jira.mycompany.com — a hostname that stopped answering the day you cut over.

It is a common post-migration complaint, and it has a specific cause worth understanding, because the fix is different depending on where the link is.

Why the migration leaves links behind​

The Cloud Migration Assistant understands structure. It knows a page in space ENG called "Onboarding" should become a page with a new ID at a new URL, and it rewrites the links that point at that page. That is the part it is good at, and for content that was linked properly, it works.

What it cannot do is interpret a URL that someone typed as text. Those are just strings to it:

The pattern is that the further a link is from Confluence's own page model, the less the migration knows about it. And the further from the model it is, the more likely a human put it there by hand — which is exactly the case the tooling cannot handle.

Step 1: find what is actually broken​

Start with the old domain. Confluence CQL's ~ operator — which Atlassian's operator reference calls CONTAINS — does what you need here:

text ~ "jira.mycompany.com"

One caveat worth knowing before you trust the results: ~ is a fuzzy token match, not a literal string match. It will also return pages that merely mention the old domain rather than link to it. Budget for a manual pass over the hits — which you need anyway, because the next step is a rewrite.

Run it for three things:

• Your old Confluence domain — self-links that were typed rather than picked
• Your old Jira base URL — worth its own sweep, because Confluence pages reference Jira issues constantly
• Any third-party host that also moved, if you had a self-hosted plugin domain

Then sweep the places CQL will not reach. This matters because text is a master field covering title, content body and labels only — comments are not part of it, so a comment link will not appear in the query above at all.

• Comments. A link someone pasted into a comment three years ago is still sitting there verbatim, and the CQL text search will not find it. Check these in the UI.
• Blog posts. Selectable explicitly with AND type = blogpost.
• Macro parameters. A chart macro pointed at your old Grafana, or a filter macro pointed at your old Jira, is a config value the migration has no reason to touch. CQL has a macro field, so macro = jira lists every page carrying a Jira issue macro — a good place to check for stale issue links.
• Attachment filenames and page properties.

If you want to see the scale before you commit to a fix, run the query once per space and compare counts. Confluence CQL has no grouping operator at all — its documented keywords are AND, OR, NOT and ORDER BY, with ASC and DESC as sort modifiers — so there is no way to ask for a per-space tally inside a single query.

Step 2: define the mapping rules before you touch anything​

Do not start with find-and-replace. Start with a rule table, one row per domain:

Rules are safer than replacements for three reasons. They are explicit about which paths are in scope. They are auditable — you can print the rule set and check it. And when one rule is wrong, you fix one rule instead of hunting through every page it already damaged.

The mistake to avoid is a blanket old-domain-to-new-domain replacement applied to every URL. Some old paths are genuinely gone and should become something else entirely. Blanket replacement turns those into confidently-wrong new URLs, which is harder to detect later than the original 404.

Step 3: preview, then fix​

Every candidate match should show you three things before you approve it: the page it lives on, the URL as it is now, and the URL it would become. Then you can accept, skip or fix each one.

This is worth insisting on even when the rule looks obviously safe, because of the Jira case below.

The Jira links inside Confluence need their own mapping​

If your Confluence pages link to Jira issues and Jira migrated separately, a domain swap is not enough on its own. The Cloud Migration Assistant records an issue key to cloud-ID mapping for the migration; apply that mapping rather than guessing, so the rewrite follows the real transformation instead of a pattern match.

Getting this wrong produces links that look right and go nowhere: correct domain, wrong key.

Step 4: verify with a re-scan​

Re-run the same searches after the fix. Two things you want to see:

• Zero matches on the old domain. Anything left is a rule you did not write.
• No new breakage. Spot-check a handful of pages you rewrote by following a few links out from them, especially into Jira. A page can be fully rewritten and still contain one link the rule did not match because of a trailing slash or a slightly different casing.

Keep the record of what changed — which page, which URL, which rule, when. When someone reports a broken link in month three, that record turns a search into a lookup.

Doing this on a schedule​

Migration is not the only way legacy URLs appear. An app is renamed, a domain is rebranded, a third-party service is retired. Any of those leaves the same residue.

Running the old-domain sweep a few weeks after cutover — and once more after the first quarter — catches the stragglers that the first pass missed. Comments surface slowly: people find old links months later and report them one at a time, because nothing tells them the link is dead until they click it.

Sources​

• Advanced searching using CQL — Atlassian Developers — the ~ CONTAINS operator, the text master field, and the absence of a grouping operator
• Advanced searching using CQL — Atlassian Developers — ~ CONTAINS, the text master field, keyword list
• Cleanup guide — Atlassian Documentation — Atlassian's framing of cleanup as routine maintenance

A Confluence instance does not rot all at once. It accumulates. A project wraps up and its space stays. A team splits and both halves keep the old runbook. Someone copies a page instead of linking to it, and now two versions exist with different numbers in them. Five years later a new hire searches for the onboarding doc, lands on the 2021 version, and trusts it.

The cleanup instinct is right. The problem is that "find stale pages" is one of those tasks where the answer depends entirely on which Confluence plan you happen to be on, and almost nobody knows that until they go looking. Here is what each tier actually gives you, in the order you should try it.

The native way: content manager (Premium and Enterprise)​

Confluence ships this tool and it does one specific job. Per Atlassian's documentation, it is an admin tool in Confluence Premium and Enterprise, and Confluence Standard users have no access to it.

Space settings → Content manager → Last active

The filter shows pages that haven't been viewed, updated or commented on. The dropdown offers four fixed options: Over 7 days ago, over 1 month ago, Over 3 months ago, Over 6 months ago. From there you can archive (up to 500 items at a time), delete (up to 100), change owner, change status, or apply an automation flow to the selection.

Three things about it are worth knowing before you plan a cleanup around it.

Limit 1 — it is one space at a time​

The tool lives under Space settings and operates on a single space. There is no site-wide version. If you run 40 spaces, an instance-wide audit means opening the same screen 40 times and merging the results yourself. That is a common reason people end up writing a script instead.

Limit 2 — it skips every page that has children​

This one is documented, though the wording deserves care. Atlassian's content manager page states:

"Last active" won't return a complete list. It specifically filters pages that don't have children. This serves as a safety measure due to the way permissions are inherited in Confluence. — Atlassian: Clean up a space with the content manager

Read that literally and it reads as excluding childless pages. That is almost certainly a wording slip in the docs, because the rationale only makes sense the other way round: nested content inherits view permissions from its parent, so the risk being guarded against is acting on a parent without first setting explicit permissions on each page. Administrators consistently report the observed behaviour as parent pages with children being the ones left out of the list.

Either way, the conclusion for you is the same, and it is the part that matters: the list is not complete, and the pages most likely to be out of date are parent pages. The failure mode is quiet. You get a short list, it looks complete, and you archive what is on it — while the stale parents stay exactly where they were, and you conclude the cleanup worked. If you are about to run a cleanup on a space with a deep page tree, spot-check three parent pages by hand first.

Limit 3 — more is excluded than the filter name suggests​

The same documentation lists what the content tree covers and what it does not:

So the Last active filter is a filter within an already-narrowed set. Blog posts are not in the tool at all, which matters if your stale content lives in blog posts.

The route that works on every plan: CQL​

Confluence Query Language runs on Free. It is less comfortable than a filter dropdown, but it is not limited to one space, and you can export what it returns. The syntax below follows Atlassian's official CQL reference.

type = page AND lastModified < now("-365d") ORDER BY lastModified ASC

Narrow it as needed:

space = ENG AND type = page AND lastModified < now("-180d") ORDER BY lastModified ASC

Run it in Advanced search in the Confluence UI, or via the REST API if you want the results programmatically:

curl -u "you@example.com:token" \
  --get "https://your-domain.atlassian.net/wiki/rest/api/content/search" \
  --data-urlencode 'cql=type = page AND lastModified < now("-365d") ORDER BY lastModified ASC' \
  --data-urlencode "limit=100"

Response bodies paginate — follow _links.next until it is absent, or you will silently process the first batch and believe it is the whole set.

Useful variations, all taken from Atlassian's documented Confluence CQL fields:

Two details worth knowing. text is a master field covering page title, content body and labels together, so a text ~ query is broader than it looks. And label exclusions use NOT IN rather than an empty-value test: label not in (draft, review) means does not carry either of these labels, not carries no labels.

The trap: last modified is not the same as stale​

This is the part that turns a cleanup into a mistake.

lastModified measures editing. It does not measure reading. The two lists are close enough to look interchangeable in a spreadsheet, and far enough apart to archive something important.

That first row is the one that gets people. A reference page that is read constantly and never edited looks maximally stale by the lastModified measure and is the last thing you should archive.

Confluence itself doesn't settle this for you. In Atlassian's own words, the product "does not have a native function for tracking historical page views", and the feature request asking for a last-viewed page property (CONFSERVER-33386) is still open. (That article is written for Data Center, where the answer is a database query — but the underlying gap it describes is why the built-in filters on Cloud fall back to activity you can see rather than activity you can't.) View analytics do exist, but the content insights panel that carries a last-viewed value is a Premium and Enterprise capability — basic view counts sit lower, but the last-viewed field is in the paid tier.

What to do with the list​

Once you have candidates, sort into three buckets before you touch anything:

1. Archive. Unused, superseded, or a copy of something that still exists. Archived content drops out of the content tree and can still be viewed — which is why archiving is reversible and deleting is not.
2. Flag and notify. Content someone still depends on that is quietly out of date. Label it needs-review, or use the content manager's automation flow to route it to the last editor. This is the bucket most cleanups skip and most need.
3. Keep. Reference material, compliance documents, anything read regularly without being edited.

Two operational notes that save pain later:

• Deleting does not create redirects. When a page is permanently deleted, inbound links break. Check what links to a page before you remove it.
• Trash is not a backup. Deleted content can be restored from trash until it is purged. If you are deleting more than a handful of pages, export the space first.

Doing this on a schedule​

Once a quarter is a sensible cadence, and Atlassian's own guidance in the content manager documentation is explicit about the split: use the content manager for heavy bulk cleanup, and use automation flows — which the same page describes as another premium feature — to keep things tidy moving forward.

On Free and Standard you are re-running the CQL query by hand each quarter. That is the practical difference between the tiers, and it is also the reason demand for third-party tooling in this specific area exists at all: the native feature is well built, and unavailable to Free and Standard.

Sources​

• Clean up a space with the content manager — Atlassian Support — plan availability, filter options, documented exclusions, action limits
• Advanced searching using CQL — Atlassian Developers — CQL fields, operators and keywords
• How can I find which pages users have recently viewed? — Atlassian Support — "no native function for tracking historical page views", and the open feature request (Data Center article)
• Content insights and analytics — Atlassian Support — where the last-viewed field lives
• Delete, restore, or purge a content item — Atlassian Support
• Archive content items — Atlassian Support

Jira configuration does not rot the way Confluence content does — nobody notices a redundant workflow scheme on a page. It shows up as slowness. Atlassian's own cleanup guidance notes that too many custom fields can clutter an instance and affect its performance, and that every field is evaluated during create, update and index operations.

The hunt is the easy part, once you know which tool applies to you. The awkward part is that Atlassian gates its site-wide cleanup tooling to the top two plans — and the free fallback doesn't fully cover the gap.

Option 1: Site optimizer (Premium and Enterprise)​

Settings → System → Site optimizer

Atlassian's documentation describes it as a central hub for monitoring and improving the health of your Jira data, with actions covering issue archival, custom-field cleanup and removal of unused project role permissions. The structure splits into Limits (forward-looking — how close you are to a threshold) and Guardrails (the cleanup actions themselves).

For custom fields specifically, the field optimization guide is the one to read. In Limits → Fields per space → Review you get:

• Spaces approaching or exceeding the field limit
• Unused custom fields that may be suitable for cleanup
• How field usage has changed over time

For each unused field it shows the type, contexts, screens, last-used date and a recommendation, and offers to move it to trash — recoverable for a limited period before it becomes permanent.

The Limits view is the part people miss. It reports how close you are to a threshold before you hit it, which is worth checking quarterly whether or not you think you have a problem.

Option 2: what the Atlassian CLI actually covers (and doesn't)​

The Atlassian CLI (ACLI) is Atlassian's own free tool for Jira Cloud, available on Windows, Linux and macOS and on all Jira Cloud plans. It's genuinely useful — but set your expectations correctly for this particular job.

Its modern command structure is acli <product> <feature> <action>, for example acli jira workitem search or acli jira project list. You may find older examples online using an --action flag style, for instance acli --action getWorkflowList. That syntax belongs to the previous generation of the tool and does not work with the current one.

And for configuration cleanup specifically, the gaps are decisive:

• There is no acli jira workflow command. Workflows, workflow schemes, statuses and transitions are not covered by the CLI.
• acli jira field handles field definitions only — create, update, delete, cancel-delete. There is no list subcommand, so it cannot enumerate your custom fields for you either.

One practical warning if you script around it: check that a subcommand actually exists before relying on it. Run acli jira --help and read the output rather than trusting that a command ran without complaint.

Option 3: the per-scheme optimizer (all plans)​

This is the option most people miss, and it changes the picture for lower tiers. Optimize field configuration schemes is documented as available on Free, Standard, Premium and Enterprise:

Settings → Work items → Field configuration schemes → Optimize scheme

It scopes the analysis to one scheme rather than the whole site, and gives Atlassian's explicit definition of an unused field. The tool reports which fields can be reduced; you can then remove them from the scheme, create an optimized variant for a selected space without changing the original, or delete a scheme that is no longer associated to any spaces.

Atlassian defines unused as all of these being true:

1. Haven't been used on a work item in the last two years
2. Aren't associated to a screen or scheme
3. Were made by a Jira administrator — not created or used by Jira, a plugin, or a Connect or Forge app
4. Aren't used in workflows
5. Aren't used in Forms

The third condition is the counter-intuitive one: the field must have been made by a human admin. It excludes system fields created by Jira itself or by an app, which are not yours to delete.

Option 4: manual checks​

When none of the above fits, these need no tooling at all:

Workflows. Go to Settings → System → Workflows. Look for workflows whose only associated scheme belongs to a project that no longer exists. Atlassian's own advanced cleanup guidance recommends verifying that no validator or post-function on a workflow depends on a custom field before deleting it.

Fields. Settings → Work items → Fields lists every custom field. The ones worth auditing are those nobody can name a use case for — cross-check each against whether it appears on a screen, in a workflow, or has a value on any work item.

Screens and screen schemes. These accumulate silently, and Atlassian's cleanup guidance calls out screens with no scheme, no workflow and no populated tab as candidates for removal.

The rule that catches people: archived is not gone​

An archived project still references its schemes. A workflow whose only scheme is attached to an archived project still has a live referrer, and deleting the workflow will break transitions on anything you restore later.

This is why "no scheme references it" is necessary but not sufficient. Before deleting, check whether the scheme is attached to an archived project, and if so whether that project is genuinely finished or merely dormant.

Remove in this order​

Atlassian's guidance on custom fields is a ladder, and the order matters because the rungs are not equally reversible:

1. Remove from the screen. It stops appearing on create, view and edit. Values on existing work items are untouched. Fully reversible.
2. Remove from the scheme. Narrower, still reversible.
3. Remove from the instance. Only now consider it. This is where data becomes hard to recover, and Atlassian explicitly warns against treating a database query as proof — confirm in the UI that the field has no data before you get here.

Sources​

• What is the Site optimizer? — Atlassian Support — plan requirement, scope
• Optimize fields per space — Atlassian Support — Fields per space review, last-used date, move to trash
• Optimize field configuration schemes — Atlassian Support — all-plans availability and the five "unused" conditions
• Install Atlassian CLI — Atlassian Developers — current command structure
• Download supported ACLI packages — Atlassian Developers
• Advanced cleanup — Atlassian Documentation — workflow and screen guidance

Text-defined diagrams — Mermaid and friends — are what AI speaks natively. They're source code, so a chat agent can read them, write them, and revise them. We shipped exactly that last week: an AI agent for Mermaid in Confluence.

Whiteboards are the other world. Freeform shapes, hand-drawn lines, arrows you drag where they need to go — the format that's actually intuitive to put in front of people. Every team has one: the architecture board on the team page, the incident flow everyone references, the onboarding map. And AI couldn't touch any of it. Ask a chat agent for a change to a whiteboard and you'd get a text description of a change, and someone still had to open the canvas and do it by hand.

That gap is why whiteboards go stale. Editing shapes one drag at a time is slow enough that nobody does it, and AI — the thing that was supposed to make maintenance cheap — had no way in.

The AI agent in Excalidraw Plus Whiteboards & AI Agent for Confluence closes the gap: the whiteboard stays what it always was — visual, intuitive, for people — but now you can operate it in plain language, from Confluence chat.

Quick answer: Open Confluence chat on any page and describe the board — "make an architecture diagram of our checkout system" draws it as an Excalidraw whiteboard right on the page. Follow-ups edit the existing shapes in place ("rename Service A to Auth Service"), the agent can search a whole space for boards, and it converts Mermaid and PlantUML into editable Excalidraw whiteboards — and back.

The agent lives in Confluence chat, next to the board it operates on.

What the agent can do​

The edit verb is the one that changes how whiteboards live. Until now, a board was a snapshot: right the day someone drew it, wronger every sprint after. When the agent can rename, move, group, and restyle individual shapes on command, "update the board" becomes a sentence instead of an afternoon.

The bridge runs both ways​

The convert verb deserves its own note, because it's the literal bridge between the two worlds.

Text diagrams are easy for AI to write and awkward for people to read — raw Mermaid syntax is not what you put on a screen in a design review. Whiteboards are the opposite: great for people, opaque to machines. The agent moves work across that line in whichever direction the moment needs:

• Mermaid → Excalidraw. That flowchart definition sitting in a code block on your page becomes real shapes you can drag, restyle, and extend — and then keep maintaining by chat.
• PlantUML → Excalidraw. Same deal for the older PlantUML diagrams many teams have lying around.
• Excalidraw → Mermaid. And when a board needs to live as text — to diff in a PR, to version with the code it documents — the agent converts it back out.

Converted boards are real elements on the canvas, not screenshots. Everything the agent can do afterwards — edit, style, layout — applies to them the same as to anything drawn by hand.

If you read the Mermaid agent post: that agent lives on the text side and turns text into rendered diagrams. This one lives on the canvas side and turns text into editable drawings. Same chat, two destinations — pick by audience, not by tool.

A working session​

The scenario this was built for: the architecture board on your team page, three sprints out of date.

1. Open Confluence chat on that page and start where the board is wrong: "Rename Service A to Auth Service, and add a caching layer between it and the database."
2. Keep going in the same breath: "Group the three AWS boxes into one container, and make the whole group green."
3. Tidy up: "Lay this out top to bottom." The agent rearranges the board into a clean top-down flow — you're not dragging eleven boxes into alignment yourself.
4. Then answer the question you actually get asked: "Which other pages in this space have architecture diagrams?" — because there are always four more, equally stale.
5. Hand off when it matters: the board is a normal Excalidraw macro. Anyone can click it and adjust by hand; the agent checks the latest saved version before each write, so its edits don't overwrite what a teammate changed an hour ago.

A detail that matters on real pages: one page can hold several boards, and the agent keeps track of which is which. "Update the deployment flow, not the network map" works.

Where you take over​

The agent is honest about its limits, and so are we:

• Layout is deliberate, not freeform. Auto-layout today means top-to-bottom flow or a grid. Ask for a radial tree and the agent will tell you those are the two it does — then you arrange the rest by hand, once, and the board stays put.
• Chat shows no pictures. The agent works on the board's data, so it replies with what changed and a link to the page — you look at the result where everyone else will.
• Deletion has a seatbelt. Ask it to remove one of five similar boxes and it checks with you first, rather than guessing which one you meant.
• Anything sacred stays hand-drawn. For boards that are compliance artifacts or just carefully art-directed, edit on the canvas as always — nothing the agent does is locked in, and nothing you hand-tune gets quietly redrawn.

Not an agent-only app​

The chat is one of two ways in, and the classic editor is unchanged — type /excalidraw and you get the full whiteboard: freehand drawing, 220+ built-in shape libraries, templates from flowcharts to wireframes, and built-in Mermaid rendering in the same app. Manual first, agent when you want speed. Both write the same kind of macro, so a board that started in chat is indistinguishable from one drawn by hand.

Prompts to try on your first day​

• "Draw an architecture diagram of our checkout system — web, API, payments, inventory."
• "Rename Service A to Auth Service and move it next to the API gateway."
• "Group the three AWS boxes and make them green."
• "Which pages in this space have Excalidraw diagrams?"
• "Convert the Mermaid flowchart in this page's code block into an editable whiteboard."
• "Lay this board out top to bottom."

Related resources​

• Excalidraw Plus Whiteboards for Confluence — full feature guide and documentation
• Mermaid AI Agent for Confluence — the text-side twin: create, read, update, and convert Mermaid by chat
• draw.io vs Mermaid in Confluence — when the source text stays the diagram, and when shapes win
• Best diagram tool for Confluence — Mermaid vs Excalidraw vs Graphviz

Ready to try it? Install Excalidraw Plus Whiteboards & AI Agent for Confluence → — free for up to 10 users.

The AI agent in Mermaid Plus Diagrams & AI Agent for Confluence closes that gap: it creates, reads, updates, and converts Mermaid diagrams directly on Confluence pages and blog posts, from chat.

Quick answer: Open Confluence chat on any page and describe the diagram — "make a sequence diagram of our login flow" renders a Mermaid diagram on the page. Follow-up prompts revise it in place, the agent can convert code blocks already on the page into rendered diagrams, and every diagram stays fully editable in the macro editor afterward.

The four things the agent can do​

The convert verb is the quiet workhorse: plenty of pages already carry Mermaid source in a code block, pasted from a repo or a PR review. Until now those blocks were dead text on the page — the agent turns each one into a living diagram without anyone re-pasting it into a macro.

Walkthrough: from prompt to published diagram​

1. Install the app from the Atlassian Marketplace — free for up to 10 users.
2. Open Confluence chat on the page or blog post you're working on and describe what you need. Concrete prompts that work well:
   • "Make a flowchart of our incident escalation path, from alert to postmortem."
   • "Draw a sequence diagram of the checkout service calling payments and inventory."
   • "Create an ER diagram for the orders and customers tables."
3. Iterate in chat. Follow-ups like "add a retry loop around the payment call" or "make this better" update the diagram in place — you don't rebuild from scratch, and the macro's settings carry over.
4. Verify the render. The diagram lands on the page rendered, not as raw text — what you see in chat is what readers get.
5. Fine-tune by hand if needed. Click the diagram, select Edit, and the side-by-side editor opens: Mermaid source on one side, live preview on the other.

Where you take over from the agent​

The agent is fast at first drafts and mechanical conversions. You stay in charge of the parts that need judgment:

• Exact layout and styling. Themes, custom colors, and fonts are set in the macro editor — the same controls as before, unchanged.
• Sensitive diagrams. For compliance or audit artifacts, review the source the same way you'd review any generated content. The source is plain Mermaid text, so the review is a diff, not a screenshot.
• Anything highly specific. If the tenth revision still isn't right, editing the 5 lines of Mermaid directly is faster than describing the eleventh.

That escape hatch is the point of the design: the agent and the editor share one source of truth. Nothing the agent produces is locked in, and nothing you hand-edit gets overwritten by chat later unless you ask for it.

Not an agent-only app​

The chat is one of two ways in. The classic editor is still there — type /mermaid in the editor, and you get:

• All 30 Mermaid v12 diagram types — flowcharts, sequence, class, state, ER, Gantt, pie, C4, mindmaps, ZenUML, use case, and more
• A one-click template for every type, so nobody starts from a blank canvas
• Live preview as you type, so syntax errors surface before save
• Dark mode that follows each reader's Confluence theme automatically
• Re-editable diagrams — source and settings are fully preserved after saving

Manual first, agent when you want speed. Both write the same kind of macro, so a diagram that started in chat is indistinguishable from one typed by hand.

Prompts to try on your first day​

• "Make a flowchart of our release checklist."
• "Turn the API example in this page's code block into a sequence diagram."
• "What does the current state diagram on this page say?"
• "Add a decision node after the build step — if tests fail, go back to dev."

Related resources​

• Mermaid Plus Diagrams & AI Agent for Confluence — full feature guide and documentation
• Excalidraw AI Agent for Confluence — the canvas-side twin: create, edit, search, and convert whiteboards by chat
• How to create Mermaid diagrams in Confluence — the step-by-step editor walkthrough
• draw.io vs Mermaid in Confluence — when the source text stays the diagram, and when shapes win
• Best diagram tool for Confluence — Mermaid vs Excalidraw vs Graphviz
• All 30 Mermaid diagram types — complete reference

Ready to try it? Install Mermaid Plus Diagrams & AI Agent for Confluence → — free for up to 10 users.

A 4,000-word runbook. A 300-row release checklist. A training doc with five chapters. Sooner or later every Confluence space hits the wall: the page that takes forever to scroll, buries the section the reader needs, and times out in the editor when someone tries to reorganize it. Pagination is the standard fix everywhere else on the web — and Confluence doesn't have it, a gap the community has flagged since 2018. Here's what actually works instead.

What Confluence paginates natively (and what it doesn't)​

The rest of this post is about the two no rows.

Method 1: page series with Previous/Next buttons (best for guides and runbooks)​

The document-style fix: each chapter becomes its own page, and readers page through with ‹ Prev | Next › controls at the bottom — the same pattern as this article series or a book.

1. Split at natural boundaries. Break the long page into chapters. Create child pages under the parent (page tree → move), so the series stays organized and each part gets its own URL and search entry.
2. Leave a hub on the parent page. A short intro plus a table of contents linking every part. Anyone landing on the old URL still finds the whole series.
3. Add Pagination Buttons for Confluence — type /pagination, then paste the previous and next page URLs in the macro config. Button style is symbol or text; layout options include center and space-between so the pair sits at the edges of the content, the way readers expect.
4. Repeat per page. First page gets only a Next URL; last page only a Previous.

Why this beats one long page: each part loads fast, gets its own search result, and comments stay scoped to the section they're about. The cost is maintenance — inserting a chapter means re-numbering and re-wiring the buttons around it. Series that change weekly are better off as Method 2.

Method 2: in-page chunking with tabs and expand (best for content that stays one page)​

When the content belongs together — reference material, an FAQ, a spec — keep one page and hide the bulk behind interaction:

• Tabs separate modes or audiences: a Setup / Usage / Troubleshooting split reads as three short pages. Details and comparisons in Tabs in Confluence.
• Expand sections hide long sub-blocks behind a one-line title — the pattern Atlassian's own docs use. Details in Expand macro for Confluence.

Both are native-capable (expand is built in; tabs come from a template or a macro). The limit: they paginate attention, not rendering — everything is still on the page and in the export. For a 300-row table no amount of collapsing helps; that's Method 3.

Method 3: long tables — restructure instead of paginate​

There is no way to paginate a native Confluence table today. The working patterns:

The summarize-on-top pattern is the highest-value one: readers who need "where are we now" get a fast answer, and the archive stays in place for the few who need it.

What about the REST API?​

If you landed here writing an integration: Confluence's API paginates with a limit parameter and cursor-based _links.next URLs — see Atlassian's REST API pagination docs. That governs API responses only; it doesn't change what readers see on a page.

Related guides​

• Tabs in Confluence — native layout tabs vs tab macros
• Expand macro for Confluence — collapsible sections, native vs styled
• How to add a block quote in Confluence — formatting long-form content
• Pagination Buttons for Confluence — the Prev/Next macro used in Method 1

Inline code — monospace text on a subtle background — is how you mark up variable names, file paths, key names, and short commands inside a sentence: set MAX_RETRIES = 3, edit ~/.zshrc, or run kubectl get pods. Confluence Cloud has three ways to produce it, and each fits a different moment: formatting as you go, typing Markdown, or bringing Markdown in from your repo.

Method 1: the keyboard shortcut (standard editor)​

1. Select the text you want in monospace.
2. Press Ctrl+Shift+M (Windows/Linux) or Opt+Shift+M (Mac).

The selection turns into inline code immediately — press the shortcut again to toggle it off. The same style is in the toolbar: select text, open the text formatting menu, and pick Code.

One Mac quirk worth knowing: Atlassian lists two code shortcuts. Opt+Shift+M applies inline code to a selection (text formatting), while Cmd+Shift+M creates a code block (block formatting). If you wanted a highlighted snippet and got a whole code section instead — or the reverse — that's the split you hit. On Windows both are Ctrl+Shift+M.

To see the full shortcut list on your site, press Ctrl+/ (Cmd+/ on Mac) while editing.

Method 2: backtick autoformatting while you type​

The Confluence Cloud editor parses a set of Markdown shortcuts as you type, and inline code is one of them: type a backtick, the text, and a closing backtick, and it converts to inline code on the closing tick — the same mechanic as **bold**, *italic*, and ~~strikethrough~~.

Type this:  `MAX_RETRIES`
Get this:   MAX_RETRIES in inline code style

This is the fastest method if your hands are already on the keyboard — no selection, no menu.

The catch: autoformatting only runs while typing. It is not a paste converter.

Method 3: pasted Markdown (Enhanced Markdown)​

If your content starts life as Markdown — a README, a runbook, an architecture doc with inline code, fenced code blocks, and diagrams — pasting it into the standard editor lands every backtick as a literal character. Retyping them works for one sentence, not for a 200-line document.

Enhanced Markdown for Confluence takes the paste directly: inline code, fenced code blocks with syntax highlighting, tables, math, and Mermaid diagrams all render from the pasted source, and the Markdown stays re-editable on the page — fix a variable name by editing the line, not by re-importing. The full syntax coverage is in the user guide.

Inline code vs code block — which one where​

Rule of thumb: if it fits inside a sentence, inline code. If it needs its own lines, a code block.

Styling limits (and what apps add)​

Native inline code has exactly one style: monospace font, light background, no options. There is no theme, no per-space color, no size control — and no way to add a second emphasis level next to bold and italic.

If pages need styled code at the block level — themes, custom colors, highlighted lines — Modern Code Blocks handles that; inline code stays native either way. For teams living in Markdown, Enhanced Markdown covers the paste path described above. And if what you actually want is a colored label rather than code — a chip that says In review or Deprecated — Confluence's native status element (type /status) is the closer tool.

Related guides​

• How to make text bold in Confluence — the sibling text-formatting shortcut and **bold** syntax
• Markdown code blocks in Confluence — fenced blocks, highlighting, and themes
• How to write Markdown in Confluence — the full syntax the editor supports
• Paste Mermaid diagrams into Confluence — the repo-Markdown paste workflow, end to end

Every Confluence team ends up choosing a diagram tool, and most start by asking the wrong question: does it support Mermaid? These days, two answers exist. Mermaid Plus Diagrams & AI Agent for Confluence is built around Mermaid — all 30 Mermaid v12 diagram types, a code editor with live preview, one-click templates for every type, and a Rovo AI agent that works on the page. draw.io is the most-installed diagramming app on the Atlassian Marketplace, with deep shape libraries, whiteboarding, and a Mermaid importer added to its editor.

Both are good tools. This guide compares how they behave in Confluence specifically — how a diagram is created, what is stored on the page, what happens when you need to change it six months later, and what it costs.

draw.io added Mermaid in 2026 — here is what actually changed​

draw.io ships Mermaid support in its editor: Arrange > Insert > Mermaid, or the + button in the toolbar. The diagram type is detected from the first keyword of your source, and draw.io's documentation lists 29 supported Mermaid keywords — flowcharts, swimlanes, class, state, sequence, ZenUML, ER, requirement, C4, Gantt, journey, kanban, timeline, gitGraph, pie, XY, quadrant, radar, Sankey, treemap, mindmap, block, packet, architecture, Venn, Ishikawa, treeView, Wardley and event modeling. A type outside that list comes back as unsupported diagram type; a broken body comes back as a parse error pointing at the problem.

The significant change landed in July 2026. Previously, inserting Mermaid flattened the diagram into an image — you could see it and nothing more. Now, by default, the Mermaid source is rendered with native draw.io shapes inside a Mermaid container group, with the source attached to that group. That means:

• You can restyle it with draw.io's Style tools — fill and line colours, text colours, fonts, labels. Your edits override Mermaid styling and survive regeneration.
• You can move and resize shapes and repath connectors inside the group.
• You can re-edit the source — select a shape in the group, click the pen icon, change the Mermaid, click Apply to regenerate.
• You can lock it with the padlock icon, or insert it as a single uneditable SVG image if you want a read-only diagram.
• You can pick the layout engine — Dagre by default, with an ELK option for neater orthogonal connectors on large graphs.

This is a real capability, and any comparison that still claims "draw.io cannot do Mermaid" is out of date. It also narrows the gap: draw.io can now hand you a Mermaid diagram and let you finish it as a polished visual artefact.

The real difference: what the source becomes​

Here is the honest core of the comparison. Both tools accept the same text:

sequenceDiagram
    participant Docs as Confluence
    participant CI as CI pipeline
    participant Reg as Registry
    CI->>Reg: push image
    Reg-->>Docs: webhook updates page
    Docs->>Docs: rerender Mermaid diagram

What each tool does with it next is the whole story.

In Mermaid Plus, the text is the diagram. The Mermaid source is stored as the macro's source. Page history shows a readable text diff, so you can see that someone added a Docs->>Docs: rerender arrow on a given date. Changing the diagram means changing a line and saving. The source is greppable, reviewable, and copy-pasteable into a pull request, a code review, or a chat with an AI assistant.

In draw.io, the text becomes shapes. The Mermaid source is used to generate native draw.io shapes inside a container group. The source is still attached (that is the July 2026 improvement), but the diagram in the page is now shape and XML data. Your restyling, manual resizing and repathed connectors live alongside the generated geometry, and regenerating from source overrides geometry changes. Practically: you can style it freely, and you can still regenerate — but the page is no longer a text document, and a page-history diff is not a readable description of what changed.

This is why the two tools attract different teams. If your diagrams are artifacts of your documentation, text-native wins. If your diagrams are designs you will present and iterate on visually, draw.io's model wins.

Mermaid Plus Diagrams & AI Agent for Confluence​

Mermaid Plus Diagrams & AI Agent for Confluence is a Mermaid editor, not a general-purpose canvas. Everything about it follows from that.

• All 30 Mermaid v12 diagram types — flowcharts, sequence, class, state, ER, Gantt, pie, C4, mindmaps, ZenUML, use case, journey, requirement, gitGraph, and the rest — each with a one-click Quick Template, so you start from working code instead of a blank canvas.
• Live preview beside the code — syntax errors surface while you type rather than when a reader opens the page.
• Text-native storage — the source is the document. Page history, diffs, copy-paste and "edit one line" all work the way your team expects from code.
• A Rovo AI agent that works on the page — see the next section.
• Themes, custom colors and fonts, and automatic dark mode so diagrams follow the reader's Confluence theme.
• Free for up to 10 users, running on Atlassian Forge with no external rendering server.

The Rovo agent: AI on the page, not just in the canvas​

The agent shipped with the current version of the app and it is the part that has no draw.io equivalent. Four capabilities, all operating on the page you are looking at:

• Create — describe what you want ("make a flowchart of our deployment process") and the diagram renders in place on the page.
• Read — ask for the source and version of a diagram and get it back in chat, so you can diff, copy or paste it into a repository.
• Update — say "make this better" and the agent revises the diagram in place, preserving the macro's settings.
• Convert — turn code blocks that are already on the page into rendered diagrams. This is the fix for the most common Confluence Mermaid failure: an AI assistant or a colleague pasted a Mermaid code block into the page and it stayed dead text.

Privacy: the diagram and the AI both stay inside Atlassian​

This is the part that decides the question for a lot of enterprise teams, so it is worth being precise rather than reassuring.

The diagram is Atlassian data, not vendor data. Mermaid Plus runs on Atlassian Forge and stores the Mermaid source as native content on the Confluence page. It is searchable, permissioned by Confluence's own rules, and versioned by page history. There is no second copy in a vendor account, because there is no vendor account.

The agent is Atlassian's, not a bolted-on third-party AI. Rovo is part of Atlassian Cloud and ships inside the platform, included with Standard, Premium and Enterprise plans. You do not sign a separate DPA with an AI vendor, create an account with one, or add one to your app inventory. The vendor whose AI you are evaluating is us — the app vendor — and the AI itself is Atlassian's.

Your inputs are not used to train anyone else's models. Atlassian states that Rovo inputs and outputs are not used to train, fine-tune or improve third-party LLM models or services, that its third-party-hosted LLM partners operate under strict zero data retention agreements, and that no provider retains the data you submit or the responses you receive. Requests are sent per-request over an SSL-encrypted connection, processed for the response, and returned.

The agent inherits Confluence's permissions. Rovo honours existing permissions, so it cannot read a page or act on content the person asking does not already have access to. Page restrictions apply to the agent exactly as they apply to the reader.

Admins keep the controls. AI features are managed from Atlassian Administration, Rovo activity is visible in the audit log, and Rovo data can be pinned to the same region as your Jira and Confluence data. Cloud Enterprise organisations can go further and elect to use only Atlassian-hosted LLMs, which keeps inference inside the Atlassian Cloud boundary rather than routing it to an external provider.

Two honest caveats, because a privacy section without them is just marketing. By default, Rovo routes requests to third-party-hosted model providers to generate the response — under the zero data retention terms above, and listed in Atlassian's public sub-processor list, so your security team can review exactly who is in the path. And Rovo retains chat and agent inputs and outputs for 30 days for safety and security purposes, while Atlassian may use de-identified, aggregated metadata to fine-tune open-source models that run inside Atlassian's own infrastructure — controllable through your organisation's data contribution settings.

Contrast that with draw.io, where AI generation (Smart Templates and a Generate tool that can call OpenAI, Claude or Gemini) is a feature of a third-party vendor's editor. draw.io does offer a zero egress option on its Forge app, which is a genuinely strong control — but it is an Advanced edition feature, so it is an enterprise-tier purchase rather than the default posture.

draw.io for Confluence​

draw.io for Confluence is the most-installed and highest-rated diagramming app on the Atlassian Marketplace — rated 4.8/5 across more than 1,200 reviews — run by JGraph as a Platinum Marketplace Partner. It is a mature, general-purpose diagramming suite, and for a lot of work it is the right tool. Its strengths:

• Shape library depth — AWS, Azure, Google Cloud, Cisco, IBM and other network and cloud icon sets, plus UML 2.5 and BPMN 2.0 libraries that Mermaid has no equivalent for.
• Whiteboarding in the same app — a whiteboard editor for meetings and brainstorming alongside the diagram editor.
• Migration paths — import from Visio (.vsdx), Gliffy and draw.io XML; export to XML, PDF, SVG, PNG, HTML and CSV.
• Layout tooling — auto-layout plus advanced layout containers, and an ELK option for Mermaid-generated graphs.
• AI generation inside the canvas — Smart Templates and a Generate tool that can use OpenAI, Claude or Gemini to produce a starting diagram you then edit as shapes.
• Enterprise governance — Standard and Advanced editions, a dedicated account manager, custom security reviews, and a zero-egress option on Advanced; the app is Atlassian Cloud Fortified.
• Broad platform support — Confluence Cloud plus Server and Data Center, and an equivalent app for Jira.

Where it costs you: it is a commercial license with per-user pricing from the first seat, the diagram is stored as XML shape data rather than text, and "make the diagram match the schema" is a manual re-import rather than a one-line edit.

Side-by-side comparison​

Decision framework: pick in 60 seconds​

1. Do your diagrams need to diff, review, or live in a repository? → Yes: Mermaid Plus. Text-native is the only one of the two that gives you that.
2. Do you need cloud provider icons, BPMN 2.0, or Visio migration? → Yes: draw.io. No Mermaid tool covers those stencil libraries.
3. Do you want an agent to draft and revise diagrams from a sentence, in the page? → Yes: Mermaid Plus (Rovo agent). draw.io's AI works inside the canvas instead.
4. Are you a team of 10 or fewer, or standardizing on one tool across thousands of users? → 10 or fewer: Mermaid Plus, free. Thousands: compare total cost — draw.io's per-user license against the tools you would otherwise buy for whiteboarding and diagrams.

Many teams run both — and that is fine​

The two tools do not conflict; they are separate macros and can sit on the same page. The common pattern is a split by kind of diagram: Mermaid Plus for the diagrams that are generated or versioned — schemas, API sequences, CI/CD pipelines, state machines, Gantt timelines — and draw.io for the diagrams that are designed — network topologies with vendor icons, BPMN process models, org charts, whiteboard sessions.

If you want one tool that covers both modes instead of two apps, Excalidraw plus Whiteboards for Confluence gives you a freeform canvas with 220+ shape libraries plus Mermaid import.

Frequently asked questions​

Can draw.io do Mermaid diagrams in Confluence?​

Yes — Arrange > Insert > Mermaid, or + then Mermaid. draw.io documents 29 supported Mermaid keywords, and since July 2026 the diagram is generated as native draw.io shapes inside a Mermaid container group with the source attached, so you can restyle it, resize it, lock it, and re-open the source to regenerate.

So what is the real difference between Mermaid and draw.io in Confluence?​

What happens to the source. Mermaid Plus keeps the text as the diagram — text diffs in page history, one-line updates, greppable source. draw.io converts Mermaid into native shapes, which buys styling and library freedom but makes the page shape data rather than a reviewable text document.

Which one should a Confluence team choose in 2026?​

Text-first teams — doc-as-code, AI-generated diagrams, standard types like flowcharts, sequence, ER, Gantt and C4 — should use Mermaid Plus. Visual-first teams that need cloud icon sets, BPMN 2.0, UML 2.5, Visio migration, whiteboarding, or enterprise zero-egress support should use draw.io. Plenty of teams install both and split by diagram type.

Is Mermaid or draw.io cheaper for Confluence?​

Mermaid Plus Diagrams & AI Agent for Confluence is free for up to 10 users. draw.io for Confluence is a paid Marketplace app with Standard and Advanced editions and a free trial, priced per user from the first seat. Small teams pay nothing for Mermaid Plus; a large rollout is a real line item for draw.io.

Can I move my draw.io diagrams to Mermaid Plus?​

Not automatically — a draw.io diagram is XML, not text, so there is no reliable reverse conversion. The practical route is to regenerate diagrams as Mermaid source from whatever you already have (your schema, your OpenAPI spec, your pipeline config) and paste that in.

Which has the better AI story for Confluence diagrams?​

draw.io generates inside the canvas: Smart Templates and a Generate tool using OpenAI, Claude or Gemini, producing editable shapes. Mermaid Plus ships a Rovo agent that acts on the page — it creates a diagram from a sentence, reads the source back, revises it in place, and converts Mermaid code blocks already on the page into rendered diagrams. If your diagrams are generated by AI assistants, the convert capability is the one that matters most.

Where does the diagram and the AI data actually live?​

Both inside Atlassian. Mermaid Plus is a Forge app that stores the Mermaid source as native content on the Confluence page — searchable, permissioned, and versioned like the rest of the page, with no copy sitting in a vendor account. The agent is Atlassian Rovo, part of the platform rather than a separate AI vendor you have to contract with.

On the AI side, Atlassian states that Rovo inputs and outputs are not used to train, fine-tune or improve third-party LLM models or services; that its third-party-hosted LLM partners operate under strict zero data retention agreements; and that no provider retains the data you submit or the responses you receive. Rovo honours existing Confluence permissions, its activity shows up in the admin audit log, and Rovo data can be pinned to the same region as your Jira and Confluence data. Cloud Enterprise organisations can elect to use only Atlassian-hosted LLMs, which keeps inference inside the Atlassian Cloud boundary instead of routing it to an external provider.

Two caveats worth knowing: by default requests are routed to third-party-hosted providers to generate the response, under those zero data retention terms and listed in Atlassian's public sub-processor list, so your security team can audit exactly who sits in the path. And Rovo retains chat and agent inputs and outputs for 30 days for safety and security, while Atlassian may use de-identified, aggregated metadata to fine-tune open-source models running inside Atlassian's own infrastructure — switchable through your organisation's data contribution settings.

draw.io's equivalent AI is a feature of a third-party vendor's editor. It does offer a zero egress option on its Forge app, which is a strong control, but only on the Advanced edition.

Compare the full set of Confluence diagram apps in the app catalog, or see how Mermaid, Excalidraw and Graphviz divide the work in Confluence diagram tools compared.

The diagrams live in the repository. They were written in Mermaid, they are reviewed in pull requests next to the code they describe, and they are correct as of the last commit. The documentation, however, lives in Confluence — because that is where the rest of the team reads it. So somebody copies a Markdown file across, pastes it into a Confluence page, and the flowcharts, sequence diagrams and ER models arrive as grey boxes of unrendered code.

Everyone has hit this. It is one of the most common Confluence complaints, and the usual workarounds are worse than the problem: export every diagram to PNG and re-upload them (now they rot), keep the diagrams in an external tool and paste links (readers need a second account, and the links break), or build a browser extension to force rendering on paste.

There is a better answer, and Mermaid 12 makes it better still.

Why Mermaid dies on the way into Confluence​

Two separate problems, often confused:

Confluence cannot render Mermaid at all. There is no built-in Mermaid support in the editor — no /mermaid macro, no diagram fence handling. Anything that looks like a diagram arrives as a code block. This is a product limitation, not a configuration mistake, and it is why Mermaid rendering in Confluence needs an app rather than a setting.

The import path actively flattens your content. When Markdown containing fenced diagrams is pasted or imported, the fence is treated as a code block and the page stores it as text. The information is not lost, but it is no longer a diagram — and nothing on the page will ever turn it back into one.

This is why "just paste the Markdown" does not work, and why teams end up screenshotting their diagrams.

The fix: paste into a Markdown macro​

Enhanced Markdown for Confluence is a Markdown editor that lives inside the page. Paste your file into it and the Quikdown engine renders everything as you type — headings, GFM tables, syntax-highlighted code, KaTeX and LaTeX math, and Mermaid diagrams.

The workflow is three steps:

1. Insert the macro. Type /enhanced markdown in the Confluence editor and pick the app. You get a split view: Markdown source on the left, live preview on the right.
2. Paste the whole file. Not just the diagram — the entire document. Tables, code fences, math and diagrams all render in the preview, so the page keeps one consistent look instead of a mix of pasted screenshots and live text.
3. Check the preview, then save. Diagrams render as centered inline SVG and update live as you keep typing. On save, the Markdown is stored as standard Confluence storage format, so it participates in search, exports, page history and permissions like any other page content.

Two properties matter for teams beyond the first paste. The Markdown stays re-editable source on the page, so updating a diagram later means changing a line — not re-importing the file. And because the rendering libraries are bundled locally rather than pulled from a CDN, the macro stays inside your Atlassian boundary, which matters when "Runs on Atlassian" is a procurement checkbox.

What's new in Mermaid 12 for pasted docs​

Enhanced Markdown now runs Mermaid 12, and for the paste workflow the headline is not cosmetic.

UML use case diagrams (usecase-beta). This is the diagram type that requirements documents need and Markdown could not previously express. Actors, systemBoundary blocks, include/extend relationships and notes all render — so a requirements doc pasted from the repo arrives with its use case diagram intact instead of as an image or a footnote.

A refreshed default look. Mermaid 12 changes the default layout engine and colour palettes, so flowcharts, state diagrams and class diagrams come out looking better with no code change.

Richer ZenUML. ZenUML fences now support conditionals (if/else), loops (while), parallel blocks (par) and try/catch — useful when the sequence diagram you want is more than a straight list of messages.

Centered, live SVG. Diagrams render centered inline and update as you edit, so a diagram that is too wide is obvious while you are writing rather than after you have pasted the whole file.

The full Mermaid 12 picture, including the syntax for every new type, is in Mermaid 12 in Confluence & Jira.

Copy-paste: a requirements doc with a v12 use case diagram​

This is the block to paste into the Markdown source. It is the use case diagram that could not be expressed in Markdown before v12:

## Checkout use cases

```mermaid
usecase-beta
direction LR

actor Customer
actor Admin

systemBoundary Store("Online Store")
  UC1("Browse Products")
  UC2("Checkout")
end

Customer --> UC1
Customer --> UC2
Admin --> UC2
UC2 ..> : include UC1
Admin --|> Customer

note for UC1 "Available 24/7"
```

The preview shows actors connected to use cases inside the system boundary, with the include relationship and the note in place. The surrounding Markdown — the ## Checkout use cases heading, any tables, any code samples — renders in the same pane, so the requirement, its diagram and its examples arrive as one document.

What happens to diagrams you already published​

Nothing breaks. This matters enough to be precise:

• Existing Mermaid source keeps working unchanged. You do not need to rewrite a single diagram.
• Flowchart, state and class diagrams may lay out slightly differently, because Mermaid 12 uses a new default layout engine and refreshed styling. A diagram can end up looking better with no code change — but if you had fine-tuned a layout by nudging shapes, the new engine may not reproduce it exactly.
• Nothing is a stored image, so there is no migration to run. The source is the document; re-render and you get the new look.

If a diagram does come out differently, pin the old appearance by overriding the theme in the fence, or re-check the ones with hand-tuned geometry first — those are the only pages worth reviewing after the upgrade.

When a dedicated diagram app is the better choice​

Pasting Markdown is the right default for standard diagram types because the diagram arrives with the document that explains it. Reach for a dedicated Mermaid macro instead when you want:

• One-click templates for every diagram type, so nobody starts from a blank fence
• Themes, custom colours and fonts to match your brand
• An AI agent that works on the page — draft a diagram from a sentence, revise it in place, or convert code blocks already on the page into rendered diagrams
• A diagram-only workflow when the page has no Markdown to preserve

Our draw.io vs Mermaid in Confluence comparison covers the text-native versus visual-editor trade-off in full, and Confluence diagram tools compared maps Mermaid, Excalidraw and Graphviz to the job each does well.

Frequently asked questions​

Why do Mermaid diagrams not render when I paste Markdown into Confluence?​

Because Confluence's editor is WYSIWYG and has no Mermaid renderer, so a mermaid fence is imported as a plain code block and stays dead text. Paste into a Markdown macro that renders Mermaid instead — Enhanced Markdown for Confluence runs Mermaid 12, so flowcharts, sequence, class, state, ER, Gantt, pie, journey and the new UML use case diagrams all render in the live preview.

What does Mermaid 12 add for pasted documentation?​

UML use case diagrams through the usecase-beta keyword — actors, systemBoundary blocks, include/extend relationships and notes — which is exactly the type requirements documents kept losing in the paste. Mermaid 12 also refreshes the default layout and colour palettes for flowchart, state and class diagrams, and ZenUML fences gain conditionals, loops, parallel blocks and try/catch.

Will my existing diagrams break after the Mermaid 12 upgrade?​

No. Existing Mermaid source keeps working unchanged. Flowchart, state and class diagrams may lay out slightly differently because Mermaid 12 uses a new default layout engine and refreshed styling, so a diagram can look better with no code change. Nothing needs rewriting, and because nothing is stored as an image there is no migration to run.

Should I paste a whole Markdown file or convert it once?​

Paste it into the macro. That keeps the Markdown as re-editable source on the page, so you update a diagram by editing a line instead of re-importing the file. A one-time conversion makes more sense only when non-technical editors will maintain the page afterwards, since they get the WYSIWYG view instead of the source.

Is a dedicated diagram app better than pasting Mermaid in Markdown?​

For standard types, pasting is faster and brings the math and code blocks in the same document. A dedicated Mermaid macro wins when you want one-click templates per diagram type, themes and custom colours, or an AI agent that drafts and revises diagrams in place on the page.

Render every Mermaid 12 diagram type inside a Markdown document with Enhanced Markdown for Confluence — free for up to 10 users.