# The Real Cost of Migrating Confluence Macros (2026) October 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) 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[​](#the-anatomy-what-a-macro-actually-leaves-behind "Direct link to 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[​](#why-the-cost-is-always-higher-than-it-looks "Direct link to 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[​](#case-study-what-migrating-mermaid-diagrams-took "Direct link to 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[​](#the-general-checklist "Direct link to 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](https://marketplace.atlassian.com/apps/1236814/) 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](/docs/Mermaid-Plus-for-Confluence/migration.md) 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](https://community.atlassian.com/forums/discussion/3315617/what-do-you-do-with-pages-with-old-macros-when-you-decide-to-switch-confluence-macro-apps) — the "we'll migrate as we go" plan needs all the reality checks it can get. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[All Posts](/blog/archive.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [macro](/blog/tags/macro.md) * [migration](/blog/tags/migration.md) * [vendor-lock-in](/blog/tags/vendor-lock-in.md) * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md)