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.
HTML Macro Migration Guide
Learn how to seamlessly migrate the Mosaic HTML Image macro 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 Mosaic HTML Image 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.
Migration - Migrating Pages with HTML 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.
From January 2026
- Pages are imported into the new Cloud site using the Cloud Editor.
2. Review Migrated Pages
Once the migration is complete, open the migrated pages that contain Mosaic HTML Image macros.
HTML Image macros display as expected in both the Legacy Editor, and Cloud Editor. The HTML Image macro can also be edited in the Legacy editor.
Post-Migration - Switching to the Cloud HTML Macro
For the best editing experience and access to the latest features, we recommend rebuilding any HTML Image macros in the Mosaic Cloud HTML Macro.
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. Legacy HTML Image macros still appear as expected.
2. Switch to the Cloud HTML Macro
The HTML Macro in Cloud allows you to do far more than just insert images into pages. This secure, lightweight editor enables you to add HTML and CSS directly to your page, providing precise control over layout and presentation.
To display HTML Images using the Cloud HTML Macro:
- Navigate to the page you would like to edit.
- Click the Edit icon in the top-right of the page, or press `
e` on your keyboard to display the page in Edit mode. - Type /html and select the HTML Mosaic macro.
- In the macro editing window, you have the option to insert your HTML code under the HTML tab. For example:
<img src="https://images.unsplash.com/photo-1574158622682-e40e69881006?w=400&h=300&fit=crop" alt="Orange cat in blue background">
