The Real Cost of Migrating Confluence Macros (2026)
Somewhere in your Confluence right now there are pages that depend on a third-party app to render. A diagram here, a markdown block there, a whiteboard embed somewhere else. The pages are fine. The app is fine. Everything is fine — until it isn't: the vendor retires the app, gets acquired, or your team outgrows it. And then a question almost nobody has asked out loud suddenly matters: what is actually stored on those pages, and what survives?
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:
- Inventory by scanning page storage, not by asking around
- Map the formats: where each vendor keeps the source, and whether it is human-readable
- Migrate one vendor at a time, with per-page results before anything is written
- Convert in place and let page history be the rollback mechanism
- 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.