Update plain text macros in Confluence Cloud for new editor compatibility

Reading Time: 3 minutes

Confluence Cloud has been gradually rolling out a new editor in which we’ve focused on aligning the edit and view experiences so that pages look the same while editing as when published. This has required us to rethink how plain text macros work, and we’ve ultimately decided to implement them as live macros.

This blog will outline the key differences in how plain text macros will work between the two editors, and take Confluence macro developers through the steps they’ll need to take to update them.

Timeline: This change has already rolled out behind a feature flag, but will not be turned on for users until the 12 Jun 2019 so as to give developers time to update their macros.

We can enable this for individual sites, so please contact us if you or a customer would like for this to be turned on before that date.


What is a plain text macro?

A plain text macro is a macro whose body consists of plain text only and which the macro then renders as something else. Some examples include LaTeX Math and Advanced Tables for Confluence.

Plain text macros in the old editor

In the old editor, plain text macros display as a block in which users input text.

This means that users can’t see what their macro will actually look like until they publish their page, and that pages look significantly different when published to what they look like while they’re being edited.

Some macros feature a custom modal that users can access by choosing ‘edit macro’ (the pencil icon). A few macros have included previews of what will be rendered in their custom modals.

Above: The LaTeX Math plain text macro on a page that’s getting edited (old editor)
Below: The LaTeX Math plain text macro on a page that’s been published (old editor)

Plain text macros in the new editor

As one of the main focuses of the new editor is to provide a consistent and predictable experience between viewing and editing a page, the old implementation of plain text macros needed to be rethought.

Most other macros have been converted to live macros – that is, full fidelity previews of the published macros. Live macros look the same while editing as they do when published, but not all live macros are fully interactive while editing.

Above: The LaTeX Math plain text macro on a page that’s getting edited (new editor)
Below: The LaTeX Math plain text macro on a page that’s been published (new editor)

In order to turn plain text macros into live macros, we’ve moved the text input into the Confluence macro browser. This means that when a user adds a plain text macro to their page in the new editor, they’ll be prompted to input text within the macro browser, and the rendered content will then be displayed on the page.

We’ve modified the macro browser for plain text macros to have the text input take over the part of the browser that would usually display a preview.

For a user, this essentially works the same as, for example, the native Confluence Chart macro. Users specify parameters and macro content entirely within the macro browser, and the macro then renders on the page.

Turning plain text macros into live macros

  • If you don’t have a custom modal, you don’t need to do anything. Confluence will use the modified Confluence macro browser and users can input text there.
  • If you do have a custom modal, then Confluence will bypasses the macro browser and only open your custom modal. This means that you will need to ensure that users can input text through your custom modal. From a design point of view, we’d recommend also adding preview capabilities to your modal so that users can add/edit text and simultaneously see what will be rendered.

More details at CONFCLOUD-65717