Convert 3rd party Macros

Owned by Kha Nguyen
Last updated: Nov 07, 2024 by Boris Berenberg
2 min read

Supported Options

Markdown Macro for Confluence Cloud can import several Macros from other vendors into our equivalent counterparts. Currently supported Macros are:

Permission required: User must be an Admin

Starting a conversion

To start a conversion process:

  1. Go to Settings → Markdown Macros

  2. Select at least one Macro that you want to convert.

  3. Click Convert

    Note: you can only have 1 conversion process running at any given time.

How it works

Once a user has selected macros to convert and triggered conversion, our app will:

  • Impersonate that user

  • Query Confluence for all pages containing the selected macros

  • For each macro on each page, convert it to our counterparts and save the page

Dry-run mode (Available soon)

When running in this mode, the Converter will perform all steps like in a normal execution, except that it will not save the updated page back in Confluence. This is useful if you want to see a list of all pages that would be changed by your conversion request.

Unwrap nested macro

In Confluence Data Center, it is possible to nest macros inside another to create very rich content. For example:

 

 

The above images are created by nesting Modus’ Iframe macros several layers deep inside various Aura macros.

The Macro Converter is capable of lifting any supported macros out of nesting and put them at the top level so that they can be rendered normally.

When “Unwrap selected macros” is set to “No”, the Macro Converter will skip the 2 Iframe macros above and leave them as is, resulting in them being unable to render in Confluence Cloud. The failure reasons are documented in the exported CSV as well.

When “Unwrap selected macros” is set to “Yes”, the Macro Converter will attempt to lift the 2 Iframe macros out of any nesting, and put them at the top level. This operation can potentially break the layout of your pages, so proceed with caution. Using the example from Fig 1, the page source post conversion will be:

And the actual render:

Common issues

  • Lack of permission

    • The conversion process impersonates the current user, so make sure the user has read/write access to all the pages containing selected macros

  • Invalid Syntax post-conversion

    • Avono’s Macros rely on a locally installed Graphviz package (Installation ), so their Macros may use an old version whose syntax is not compatible with our backend. In this case, users will need to edit the Macro body to update to a modern syntax.

  • Javascript functionality is broken after migrating native HTML macro

    • When javascript runs in the HTML macro on-premise, it has access to all of Atlassian provided code such as AJS and jQuery. We do not provide these libraries in our macro. You will need to load whatever libraries you need via a script tag.

  • Look and feel of content is broken after migrating native HTML macro

    • When html is inlined into a Confluence page using the on-premise HTML macro, it will inherit Atlassian provided CSS. We do not provide this CSS in our macro. You will need to add whatever CSS you need to your macros to achieve the desired design.

  • Other unknown errors: users can try and rerun the conversion process again

  • Confluence’s “New Editor” will change the structure of nested macro

    • When converting a page from the “Legacy Editor” to the “New Editor”, some nested macros will be removed/updated. For example, below are the sources of the same page in Legacy vs New Editor:

  • So it is recommended to run the Macro Converter before switching your page to the new editor to minimize data loss. In case the page is already switched to the “New Editor”, it can be easily reverted to the “Legacy Editor” by going to “Page History” and then restore the page to the previous version. For example, the v24 is the version with “Legacy Editor”.