Need help migrating with Mosaic?
Whatever stage you're at, we're here to support your migration. Our team is happy to answer any burning questions or help you move confidently with Mosaic.
CSS Macro Migration Guide
Learn how to seamlessly migrate the Mosaic CSS and Div macros from Confluence Data Center to Cloud with our step-by-step guide. Ensure a smooth transition with clear instructions and best practices.
This step-by-step guide will walk you through the process of migrating pages containing Moasic CSS and Div macros from Confluence Data Center (DC) to Confluence Cloud.
Pre-Migration - Prepare for Migration
1. Audit of Macro Usage
Before beginning your migration, identify all pages using Mosaic macros, particularly any using nested macros. Our Mosaic Usage Report tool can help you do this by listing all pages containing Mosaic macros and showing their migration readiness status.
To use the Mosaic macro reporting tool:
- Click the Cog>General Configuration in the top-right corner to open Confluence Administration.
- Navigate to Mosaic Macros.
- Click Mosaic Usage Report.
- Click Start scan. The scan will begin.
- Once the scan is complete, click to Download Report.
Take note of any pages using CSS or Div macros.
Migration - Migrating Pages with CSS and Div Macros
1. Run the Atlassian Confluence Cloud Migration Tool
Refer to Atlassian’s documentation for guidance on using the migration tool.
When using the Site Import method:
- Pages are imported into the new Cloud site using the Legacy Editor.
- CSS and Div macros can be edited in the Legacy Editor.
From January 2026
- Pages are imported into the new Cloud site using the Cloud Editor.
- Mosaic Div macros appear as expected, preserving most of their functionality.
- CSS macros are not editable.
2. Review Migrated Pages
Once the migration is complete, open the migrated pages that contain Mosaic CSS and Div macros.
Div Macros
Div macros should display as expected in both the Legacy and Cloud editors once migrated. These macros can still be edited in both editors.
CSS Macros
CSS macros display as expected in the Legacy editor. The CSS macro can be edited in the Legacy editor.
Once a page is converted to the Cloud editor, the CSS macro no longer appears when editing a page and can therefore not be edited. Although the CSS macro cannot be edited, any Div macros using the previously applied CSS still work and appear as expected.
Once a page is converted to the Cloud editor, the CSS macro no longer appears when editing a page and can therefore not be edited. Although the CSS macro cannot be edited, any Div macros using the previously applied CSS still work and appear as expected.
Need help migrating your CSS and Div macros?
If you encounter issues with nested macros, unknown macros, or CSS styling, contact Mosaic support for assistance.
Post-Migration - Styling Macros in the Cloud Editor
After migration, any existing CSS styling will continue to function within the Legacy editor until January 2026.
However, once a page is converted to the Cloud editor, direct CSS editing will no longer be available.
For the best editing experience and access to the latest features, we recommend converting pages that use CSS to the Cloud editor and applying styling through the macro styling options instead. This approach ensures ongoing compatibility and makes it easier to maintain consistent page designs without relying on custom CSS..
1. Convert to the Cloud Editor
To convert a page from the Legacy editor to the Cloud editor:
- Open the page you wish to convert and click Edit.
If your page is using the Legacy editor, a notification bar will appear at the bottom of the edit screen. The first time you view a page in the Legacy editor, you can switch to the Cloud editor by clicking Update Page in the notification. - When prompted, click Preview page → Convert Page.
Alternatively, you can choose to preview the page before converting. - The page is converted to the Cloud editor. Div macros appear as normal; however, CSS macros are no longer editable or visible in the edit screen.
2. Set Styling in Macros
In Confluence Cloud, you can now set the styling of Mosaic macros directly within the macro editor. This enhancement allows all users to easily customise the appearance of their pages without requiring any CSS knowledge.
To edit the design of a Mosaic macro (for example, Buttons):
- Click on the macro in the Confluence Cloud editor.
- Select Edit.
- Adjust the styling options available in the macro editor under Appearance.
Managing the appearance of macros within the macro itself makes it easier to maintain consistent and visually appealing page designs while taking full advantage of Mosiac for Confluence Cloud’s built-in editing features.
