How to Use the HTML Macro in Confluence Cloud: Fix Migration Errors and Unlock Custom JS/CSS

For organizations migrating from Confluence Server or Data Center to the Cloud, the loss of the native HTML macro is a frequent and frustrating hurdle. Instead of the interactive content you expect, migrated pages often display a jarring "Error loading the extension!" message.

While many look to single-purpose Marketplace apps to fill this gap, there is a more powerful and cost-effective solution: User Macro for Confluence Cloud. By leveraging this platform, you can not only restore your HTML functionality but also gain access to a full library of custom macros.

The Problem: "HTML Macro Gap"

On-premise versions of Confluence have long supported an embedded HTML macro. However, this macro does not exist in the Cloud. When you migrate, Confluence looks for a macro with the key html and, failing to find it, renders an error.

Recreating the HTML Macro

The most efficient way to fix these errors across your entire instance is to register a new macro in the Cloud that matches the original's unique identifier. User Macro for Confluence Cloud allows you to do exactly this.

There are two ways of doing that:

1. Import our macro pre-defined macro

2. Or create the same by your own

1. Importing

We have prepared readu-to-use HTML macro that will work just as-is.

Download the following JSON file: html_macro_for_importing.json

[
   {
      "key":"html",
      "name":"HTML Macro",
      "authorsInfo":[
         {
            "id":"712020:bf42f99c-6236-48f1-b5de-45bdb3f14b54",
            "name":"Anatolii Starshekov _Wombats Corp_",
            "picturePath":"https://wombats-test.atlassian.net/wiki/aa-avatar/712020:bf42f99c-6236-48f1-b5de-45bdb3f14b54"
         }
      ],
      "categories":[
         
      ],
      "description":"A macro to migrate Data Center native HTML macro to Cloud",
      "usageCount":50,
      "parameters":[
         
      ],
      "documentation":"https://wombatscorp.com/user-macro-for-confluence-cloud/what-are-confluence-macros",
      "template":"$body",
      "macrosKey":"",
      "outputType":"block",
      "bodyType":"plain-text",
      "hidden":false,
      "width":"100%",
      "height":"100%",
      "iconPath":"https://user-macro.wombatscorp.com/icons/blue/h.png",
      "updatedAt":1774010618389,
      "macroType":"dynamic",
      "enabled":true
   }
]

And Import it into User Macro app:

Do not forget to select the “Keep original macro key“ checkbox.

Otherwise the key will got uniq generated suffix and will not defined as the original HTML macro.

2. Creating own HTML macro

Instruction below will create the same macro as it was listed above in html_macro_for_importing.json file. It’s another (handmade) way to achieve the same goal.

To ensure the Cloud instance automatically picks up and renders your migrated data, follow these specific settings when creating your macro:

1. Macro Key: Set this to html. This is the most critical step for migration success; keeping the key identical to the original DC/Server version allows Confluence to recognize the data immediately.

2. Macro Type: Select Dynamic. This ensures support for JavaScript, which is essential for complex HTML content.

3. Body Type: Choose Plain Text. This is vital for compatibility during migration, as it handles the raw code correctly.

4. Output Type: Select Block. This mirrors the original layout behavior.

The Template: In the template editor, simply use the following code: $body This direct reference ensures the macro body is rendered as-is.

The result

Right after saving the macro and reloading page it will work!

It’s because Confluence rendering page with html macro now know which exact macro should process this part. So it will work for all pages in the whole instance without additional actions, and even for pages with JavaScript.

On the Data Center page renders HTML macro as following:

And below how the same page rendered on Confluence Cloud:

Why This Solution is Better

Beyond just fixing broken links, using User Macro for Confluence Cloud offers several distinct advantages over standard HTML apps:

• Isolated Execution: In the Cloud, dynamic macros run in isolated, sandboxed iframes. Our tests found that while the original Server macro occasionally failed when multiple instances were placed on a single page, our app handles multiple macros perfectly because each instance is safely isolated.

• Beyond Just HTML: Instead of a one-trick tool, you get a complete macro library. You can use pre-built examples like the Page Tree View, Issue Filter, or Aggregated Page Attributes.

• Customization Power: Unlike static apps, you have the flexibility to build your own macros from scratch to solve unique business problems.

Potential Use Cases

Restoring the HTML macro opens the door to several interactive possibilities:

• Custom Data Visualizations: Use JavaScript libraries to render interactive charts or graphs directly from external data sources.

• Dynamic UI Elements: Create stylized banners, custom buttons, or interactive checklists that match your corporate branding.

• External Integrations: Seamlessly embed content from third-party APIs or internal tools that don't have a native Confluence macro.

If you are facing migration challenges or want to explore how custom macros can enhance your Confluence Cloud experience, we are here to help.

Contact us at: info@wombatscorp.com