Facing Mosaic migration challenges?
Customer Success Manager
Contact our team for tailored support:
Handling Mosaic macros in Atlassian's cloud editor
Get to grips with Mosaic for Cloud's editing experience, and learn how to ensure your macros are ready.
If you haven't heard already, Atlassian has announced its decision to discontinue the legacy editor in early 2026. This means that migrated pages will move directly to the new cloud editor.
Because pages in Confluence Cloud work differently from those in Data Center (DC), some Mosaic macros might not behave the same way, and some are no longer supported. By taking action now, you can understand which macros will be affected and avoid more cleanup work in the cloud.
Here’s your quick-reference guide to handling Mosaic macros in the new Atlassian Cloud editor, before and after migration.
Here’s your quick-reference guide to handling Mosaic macros in the new Atlassian Cloud editor, before and after migration.
Pre-migration check
We've broken this section into three parts:
- Macros that migrate smoothly
- Macros that need some modification before you move
- Key considerations about your DC macros (e.g. nesting)
About the Legacy Content macro
Atlassian introduced the Legacy Content macro to preserve the functionality of legacy macros migrated from Data Center.
What does this mean for you?
- When your pages are moved to Confluence Cloud, any legacy macros will be wrapped inside the Legacy Content Macro.
- These macros will still display and work in the cloud.
- If a macro is nested inside the Legacy Content Macro, you can still edit its content using the new cloud editor.
Below are examples of Mosaic’s macro editing experience between Confluence Data Center and Cloud. Click on a section to see the macro editing experience on each platform:
Macros that migrate with minimal issues
Alert
Note: Content shown inside the alert can be edited, but you are unable to access the macro editor itself.
Dialog, Button Group, Button Hyperlink
DC Experience
Cloud Editor
Note: On DC, you can open a Dialog from a button or a hyperlink. Following a migration, Dialogs opened by buttons work, but Dialogs opened by hyperlinks do not.
Horizontal Navigation
DC Experience
Cloud Editor
Note: The Horizontal Navigation appears and works as expected for users, but the legacy macro cannot be edited.
Progress Bar
DC Experience
Cloud Editor
Round Rectangle
DC Experience
Cloud Editor
Note: The Round Rectangle legacy macro mostly works as before, but width values are not respected.
Tabs
DC Experience
Cloud Editor
Note: Content inside the tabs can be edited after migration, but the macro editor itself can’t be accessed.
BibTeX Referencing
DC Experience
Cloud Editor
This legacy macro functions the same as the DC macro.
LaTeX
DC Experience
Cloud Editor
This legacy macro functions the same as the DC macro.
Macros you should adjust before migration
Div
DC Experience
Cloud Editor
Note: Any CSS rules applied to the Div macro are preserved, but the legacy macro itself isn't editable.
CSS Style Sheet
DC Experience
Cloud Editor
Note: The CSS Style Sheet macro editor is not accessible after migration.
Span (Inline)
DC Experience
Cloud Editor
Note: The Span macro maintains the inline status only if the content is nested within the Legacy Content macro.
What to do now:
- Review the content inside the macros that are no longer editable in Cloud
- For Round Rectangle macros, adjust widths using percentages
- Flatten layouts and rebuild using Cloud sections/columns
- Document CSS rules so you can replace them with Confluence or Mosaic styling
Important information about macro usage
Nested macros
Deep nesting (e.g., Tabs within Tabs) will continue to work in Cloud. However, CSS applied to nested macros won't consistently carry over.
Note: Most CSS applied to macros that are not nested within other macros will remain in effect.
What to do now:
- Minimise dependence on CSS
- Replace inline formatting with native editor options
- Test your most complex nested pages in a cloud sandbox, if possible
Inline macros
These macros lose their inline behaviour unless nested inside a legacy content macro:
- Span
- Copyright
- Footnotes
- Highlight
- Trademark
- Service Marks
- Strikethrough
What to do now: Replace these with built-in formatting (such as strikethrough, highlight, and emojis) before migration.
Post-migration adjustments
Some macros can only be fixed once your pages are in Confluence Cloud. Read on to learn more.
Macros that are unsupported in Cloud
These macros will appear as an 'error' in page view mode, although users can still view the content in edit mode.
- Clickable (the content will be displayed on the view page, but it just won't be clickable)
- Tooltip
- Rollover
- Restful Table
- Message Box
What to do in Cloud:
- Replace with Mosaic Dialog macros, Tabs, or standard Confluence features
- Use tables, links, or Confluence Cloud-native formatting instead of custom macros
Macros with reduced functionality
| Macro | DC Experience | Cloud Editor |
|---|---|---|
| Fancy Bullets | Custom bullets supported | Many styles don’t display |
| Table Layouts | Flexible table styling | Content shows, layout not exact |
What to do in Cloud:
- Update fancy bullet lists and tables with Cloud-native features (tables, built-in bulleted lists)
How to find pages containing Mosaic macros
To help you plan your migration, we've created a report that flags which pages include Mosaic macros (and what the macros are).
As a Confluence admin, you can access the Macro Usage Report under the administrative menu. Navigate to the Mosaic configuration, and you'll see the option to generate the CSV report.
As a Confluence admin, you can access the Macro Usage Report under the administrative menu. Navigate to the Mosaic configuration, and you'll see the option to generate the CSV report.
Once you’ve downloaded the report, follow this checklist to prepare your content for the cloud:
- Identify important pages to be migrated, such as pages with recent updates
- Flag pages with unsupported macros (Clickable, Tooltip, etc.)
- Inform the page author(s) to make the necessary edits before migrating:
- Check for deeply nested macros, such as multiple layers of Tabs, especially those with CSS styling inside them. Simplify layouts where possible.
- Make final changes to macros that are editable in DC only (Alert, Tabs, Progress Bar) and replace unsupported macros (Clickable, Tooltip, Rollover, Restful Table, Message Box) with alternatives pre-migration where possible.
What to do when you’re in Confluence Cloud:
- Replace inline formatting (Span, Highlight)
- Rebuild Div/CSS-heavy layouts using Cloud-native features (sections, columns, and tables) and Mosaic Cloud macros (Background, Advanced Cards, Tabs, Interactive Banner)
💡 For a full list of macro alternatives in Confluence Cloud, check out our guide to Mosaic migration workarounds.
