What do you do with pages with old macros when you decide to switch Confluence macro apps?

Simon_NGPILOT_

Full disclosure first: I build Mermaid Plus at NGPILOT, and serveral macro apps for Confluence, which is exactly why I’m asking instead of pitching.

Here’s the situation I keep running into, and I suspect it’s common across every macro category. A team picks a macro app — draw.io for diagrams, Excalidraw for whiteboards, a markdown macro, advanced tables, task lists, a Mermaid macro, whatever fits at the time. It works. A year or two later something changes: a new tech lead with different preferences, a feature you need lives in a different app, licensing gets painful, or the team simply falls out of love with the tool. So the team decides to switch.

And the decision process is almost entirely about the future: which app is better for the content we’re going to create. The past — the hundreds of pages that already have the old app’s macros — gets one line in the plan: “we’ll migrate them as we go.” Everyone nods. Nobody has ever actually seen “as we go” happen.

The reason it’s genuinely hard, in case you haven’t switched macro apps before: Confluence macros are stored per-app inside page storage, and every vendor wraps the content differently — one keeps the source in a macro parameter, one in attachment blob, one next to a companion block. The new app you’re switching to can’t read the old app’s format. The old app has to stay installed just to keep the existing pages rendering. A real conversion means somebody writes a parser for the old format — per app, sometimes per app version.

So I’m asking teams who have actually been through a switch:

1. What did you do with the existing pages? Convert them all in place before the cutover, freeze them and start fresh in the new app, or run both apps side by side indefinitely?
2. Did the old app stay installed just to keep old pages rendering? For how long — and what finally made you remove it?
3. Big-bang conversion or page-by-page as each page gets edited? Which one held up?
4. Did migration capability influence which new app you picked — as in, “we chose X because it could import from Y”? Or was that never a real factor?
5. And the honest one: did you just leave the old macros to die, and did it matter as much as you feared — or was the content mostly stale anyway?

The bigger question underneath: macro apps have no common interchange format, so every switch re-pays the parsing cost from scratch — and that cost quietly shapes which apps teams dare to adopt in the first place. Should import/export of existing content just be table stakes for any macro app on the Marketplace? Or is per-app migration the permanent tax of a healthy ecosystem?

Josh

Hi @Simon_NGPILOT_, good question, and you're right that "as we go" rarely happens. What has worked for me is turning "the past" into a list before anyone picks the new app.

1. Size it first. Confluence search (CQL) can find pages by macro name, for example:

macro = "old-macro-name" and type = page

Run that in advanced search or through the REST search endpoint and you get every page that still uses the old macro, per space. The macro name is the one in the page storage format, not the display name, so open one page's storage format first to get it right. Docs: https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/

2. Split the list by age. Pages nobody has edited in a year or two are usually read-only history. For those, one option is to export or screenshot the rendered output as an attachment or image and leave the page as a record. Pages people still edit are the ones worth converting.

3. Decide the uninstall date with the list in hand. If the count is small, convert by hand and uninstall. If it is large, keep the old app until the active pages are done, and put that cost in the switch decision instead of discovering it later.

Rerunning the same CQL each month also shows whether the number is actually going down.