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.
Migrating your Mosaic content
Bring clarity to your migration. Our tutorials and explainers are here to help you feel confident about moving your Mosaic content.
Moving to Confluence Cloud is a big step, and it's important to understand how the move will affect your content and users. Below, you'll find resources and guides to help you understand how Mosaic works in Cloud and everything you need to migrate a Data Center instance containing Mosaic macros.
This page covers the most common migration experiences, but if you'd like more tailored advice for your organisation, please get in touch.
Explore Mosaic for Confluence Cloud
Why Mosaic for Cloud?
From faster page creation to unrivalled app support, discover a new and better way to format your Confluence content.
If you're wondering how Mosaic works in Confluence Cloud, we're here to make it easy. We cover all the new features, differences, and benefits waiting for you.
Pre-migration considerations
Confluence Cloud offers many more built-in features and simplifies the overall user experience, but if you've used Data Center/Server for a long time, it can feel unfamiliar at first. It's important to understand these changes as they can impact what you can do as part of your migration.
What to expect in Confluence Cloud
Here are some key ways the Cloud experience differs from that in DC:
Nesting in Cloud
Confluence Cloud comes with more straightforward nesting capabilities to stop users from getting lost. So if you've got Tabs within Tabs within Tabs, these might look different after migration. Furthermore, Mosaic macros combined with other third-party macros can be unpredictable because we don't control how these other macros work in Cloud.
Legacy Editor vs Cloud Editor
When you first migrate, your pages will be saved as legacy pages, conserving your DC formatting and macros.
We've created a guide to answer your questions about the Legacy Editor, how it works, and how to convert pages to the Cloud Editor to get the most out of Confluence Cloud's newest features.
CSS
When you migrate, Atlassian tries to preserve your existing CSS as best it can. However, more complicated applications might be trickier to carry over, and the results could differ from your expectations.
From January to April 2026, all migrated pages will be automatically converted to the new cloud editor. Due to this change, the HTML/CSS Style Sheet macros will no longer be editable. To be on the safe side, we recommend:
- Documenting your CSS code and reapplying it in Confluence Cloud using Mosaic's HTML macro.
Or
- Apply styling using equivalent macros in Cloud. Learn how to create CSS-like styling with our handy set of tutorials.
Mosaic Cloud vs Mosaic DC at a glance
Confluence Cloud comes with many more built-in options for organising and styling content. This means that you no longer need many of the core Mosaic DC macros, such as the Iframe macro, because they're native to the platform.
Mosaic DC macros built into Confluence Cloud
- Align
- Center
- Div
- Iframe
- Ordered List
- Paragraph
- Search Box
- Span
- Strikethrough
- Table Layouts
- Unordered List
Because of this, our list of Confluence Cloud macros looks a lot smaller. However, these macros are more powerful and considerably more user-friendly, letting users with less technical knowledge create well-styled pages. We've even introduced a range of new Cloud-exclusive macros, like Advanced Cards and Interactive Banners, which weren't previously possible in DC.
Learn more about Mosaic’s macros in Cloud and prepare your teams for the new ways of creating content in Confluence:
Feature parity
Confluence Cloud comes with many built-in features that DC didn't have, meaning you no longer need many of the old macros to achieve the same effect. Because of this, Mosaic for Cloud offers a slimmer but much more powerful range of macros and features, as well as some new Cloud-exclusives.
We've covered every feature natively included in the Cloud Editor, what's new from Mosaic, and how to create the same or better versions of Mosaic's DC macros.
Migrate with Mosaic
Migration overview
App migration is a critical part of any Confluence Cloud move. To help you prepare more confidently, we’ve created a handy app migration checklist that highlights what to review when assessing Marketplace apps.
Mosaic Cloud migration guide
When you migrate your pages over to Confluence Cloud, your Mosaic macros will also be migrated inside those pages. You can still view and edit Mosaic macros on these pages, as long as they're wrapped inside the Legacy Content macro. For macros that are no longer supported in the new cloud editor, we've prepared detailed migration guides below.
We know that our macros are probably used across many of your pages, and may be combined with each other (and even other apps). We suggest doing a test migration of a small number of spaces to assess if there are any added complications with your migration.
Assess macro usage
To help the process go as smoothly as possible, we recommend taking an inventory of your existing Mosaic macros in Confluence Data Center. You can do this with the Mosaic Macro Usage Report.
Mosaic Macro Usage Report
We've built a dedicated tool to help you get your pages migration-ready. It lists all pages containing Mosaic macros and shows their migration readiness status.
- Click the Cog icon in the top-right corner to open Confluence Administration.
- Navigate to General Configuration.
- Under Mosaic Macros, click Macro Usage Report.
Un-nest macros to prepare for the Cloud Editor
To improve user navigation, Confluence Cloud limits the number of macros that can be nested inside each other. If your DC instance has many macros inside other macros, the migrated results may not look the same as the original.
We recommend separating macros or considering options to rebuild the functionality using Cloud macros instead.
Individual macro migration guides
If you've used the steps above to identify your most-used macros, browse our guides designed to help you migrate them as smoothly as possible.
Post-migration: Troubleshooting & workarounds
What to expect after migrating Mosaic DC macros
After migration, your DC macros will remain functional within the Legacy Editor (until January 2026).
However, to get the best experience and take advantage of all the great features of our macros for Cloud, we recommend converting your pages to the Cloud Editor when possible.
Convert pages 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. All Mosaic DC macros are now wrapped in the Legacy Content macro and cannot be edited. Click Update to save it.
Rebuilding macros using Cloud equivalents
Once you've converted your pages to the Cloud Editor, your DC macros will live in the legacy content macro container. However, this is being deprecated, so you'll need to convert your DC legacy macros to the Cloud versions.
You can find workaround suggestions for a range of macros here, or browse our full guides below.
Formatting 101: Get the look in Cloud
Our tutorials help you get the same, custom look with Confluence Cloud as you know and love in DC - without the need to use CSS.
How to create CSS-like styling effects in Cloud
Discover how to replicate the full range of CSS effects (without any coding knowledge needed).
How to overlay text onto an image
Here’s how to overlay a snippet of text onto an image in Confluence Cloud - no design tools needed.
How to apply custom colours to page text
Learn how to apply custom colours to your text in Confluence Cloud. It takes less than two minutes!
How to adjust the corner radius of images
Make your Confluence images friendlier and more professional in seconds - it's easier than you think.
How to add a colour overlay to an image
Wondering how to add a quick, simple colour overlay to an image on Confluence Cloud? Here’s how.
How to add Unicode symbols to pages
In DC, you need a macro to add hyperlinked symbols to your page. Now you can do it with Confluence's built-in features!
Discover new (and better) ways to build pages in Cloud
Embrace the move with our Cloud-exclusive tools, helping you format pages faster and easier than ever.
How to use templates to get started quickly in Cloud
Looking to kickstart your content creation? Grab a template (or 35) to build knowledge bases, wikis, team pages, and more in seconds.
How to recreate DC layouts with Smart Designer
Learn how to create (or recreate) content in seconds with our built-in pages wizard - no design skills or inspiration needed.
Frequently Asked Questions (FAQs)
How should I prepare for migrating Mosaic from Data Center (DC) to Cloud?
Preparation involves understanding which macros are used, their compatibility in Cloud, and running pre-migration checks. Use the Macro Usage Report to identify critical content and potential issues. Addressing these before migration reduces manual work later.
What are the recommended steps for a successful migration?
The process typically includes: pre-migration analysis, migration testing, actual migration, and post-migration clean-up. You can find detailed step-by-step instructions in the migration guide above.
What are the key differences between Data Center (DC) and Cloud versions of Mosaic?
Mosaic Cloud is designed as a modern, intuitive solution for Confluence Cloud, which has more limitations on HTML/CSS, nested macros, and editor behaviour compared to DC. With Mosaic Cloud, users can enjoy code-free editing, smart design tools like AI-powered Smart Designer, a broader library of templates, and built-in support for easy branding and collaboration. Mosaic DC provides granular control and supports legacy customisations, but often requires technical skills such as CSS, and places more responsibility on teams to manage infrastructure and compliance.
To learn more, read our guide to Mosaic Cloud vs DC.
To learn more, read our guide to Mosaic Cloud vs DC.
What is the Legacy Editor, and how does it affect our content post-migration?
The Legacy Editor is the editor used by Confluence DC. After migration, pages will appear in the Legacy Editor; however, Atlassian is deprecating it in April 2026.
Once converted to the Cloud Editor, some DC macros may no longer be editable or may lose functionality, so make sure to preview your pages first.
Once converted to the Cloud Editor, some DC macros may no longer be editable or may lose functionality, so make sure to preview your pages first.
What happens to macros when switching from the Legacy Editor to the Cloud Editor?
Some macros may break, lose formatting, or become uneditable. Please check our documentation on using Mosaic macros in the cloud editor for more info.
Does Mosaic support automated migration tools like Confluence Cloud Migration Assistant (CCMA)?
Some migration can be done with Atlassian’s CCMA, but manual steps are often required for complex macros. Mosaic DC comes with a built-in usage report to help you identify pages containing our macros and detailed instructions on migration steps. Some scripts and tools are available for assisting with bulk macro updates, but not all scenarios are fully automated yet.
Should we anticipate any data loss during migration?
There is a risk of data loss or formatting changes, especially for unsupported macros or complex formatting. We recommend you perform pre-migration analysis and post-migration review. Please contact us if you need assistance with your migration plan.
Where is Mosaic's app data stored, and how is it backed up?
Mosaic's data residency and backup policies depend on the hosting region and Atlassian’s infrastructure. Contact us for specifics on your instance.
Is Mosaic Cloud compatible with FedRAMP or Atlassian Government Cloud (AGC)?
Yes, Mosaic AGC is available for government customers, with specific security and feature differences. Visit the Mosaic for AGC product page for more details.
