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.
If everything looks good in the Legacy Editor, you should preview a page before converting it to the new Cloud Editor. To be on the safe side, we recommend replacing these macros referenced in the CSS Style Sheet with Cloud versions (and applying styling individually - it's quick!) before converting the page.
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.
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
Migrating to Confluence Cloud is a big undertaking, but by following the right steps, you can smooth the process for your organisation.
The general process is as follows:
- Assess your DC site (see below for more info).
- Review apps, users, and content.
- Migrate selected content and users using the Confluence Cloud migration assistant.
- Content is moved to your Cloud site as legacy pages.
- Review and tidy up content in Cloud, converting pages to the Cloud Editor where needed.
For a more in-depth look at the overall migration process, read Atlassian's documentation and download our free migration checklist.
Mosaic Cloud migration guide
When you migrate your pages over to Cloud, your Mosaic macros will also be migrated inside those pages. You can view and edit these pages and their content using the Legacy Editor.
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.
Workarounds
Mosaic combines the features of some individual DC macros into more powerful macros for Cloud, minimising clutter and confusion.
Learn how to recreate the same effects with our range of tutorials:
Create CSS-like styling in Cloud
From rounded corners to colour overlays, easily recreate your CSS and Div custom styling with our range of tutorials.
Using Unicode symbols in Cloud
You no longer need a dedicated macro to use Trademarks, Copyright Marks, and Service Marks on your page. Here's how to add one to your page.
Highlight macro workarounds
With the help of a Cloud native element or Mosaic's Background macro, you can make your content the centre of attention
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 the Legacy Editor vs 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.
