Skip to main content
Kolekti home
Contact usBook a demo

Mosaic Migration Hub

Resources to help you migrate Mosaic Data Center to Cloud
An open cardboard box with a cloud on the side, with Mosaic macro icons flying out
Get in touchTry Mosaic Cloud free
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.

Step 1: Prepare for migration

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.

Understand platform differences


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.
Mosaic Cloud vs Data Center
Screenshot of a table comparing feature parity between Mosaic Data Center and Cloud

Confluence’s 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.
More about Confluence's legacy editor

Audit your Confluence site before migration

Assess macros usage

Before migrating, it is important to understand how Mosaic macros are used across your instance, including which spaces rely heavily on them and how complex the implementations are.
To help the process go as smoothly as possible, 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.

More about the Mosaic macro report

Prepare nested macros for Cloud

It is not possible to nest macros in Confluence Cloud. If your DC instance contains many macros within other macros, the migrated results may not match the original. Furthermore, Mosaic macros combined with other third-party macros can be unpredictable because we don't control how these other macros work in Cloud.
We recommend either separating macros or rebuilding the functionality using Cloud macros. Some scripts and tools are available for assisting with bulk macro updates, but not all scenarios are fully automated yet.

Step 2: Migrate Mosaic

Mosaic migration can be done with Atlassian’s CCMA. However, manual steps are required, especially for complex macros. You’ll find more detailed guidance for migrating macros below.

Individual macro migration


When you migrate your pages over to Confluence Cloud, your Mosaic macros will also be migrated inside those pages. On the published version of the page, the appearance of the macros may change, and some may not be displayed at all. On the edit page, all of the content will be preserved.

After migration, Mosaic macros generally fall into one of the following categories:
Migration OutcomeDescription
Cloud-compatibleThe macro is supported in Confluence Cloud and continues to function with minimal adjustment.
Legacy-supportedThe macro content is preserved but may appear inside a Legacy Content macro after page conversion. Editing capabilities may be limited.
Requires rebuildThe macro is not fully supported in Cloud and should be redesigned using Cloud-native alternatives. Content inside the macro can still be accessed in edit mode.
Learn more about the Legacy Content macro

Looking to learn more about migrating specific macros? We’ve created detailed migration guides for just that purpose:
Macro migration guides

Guidance for CSS Style Sheet macro

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.
Replicate the look of CSS & Div macros in cloud

Step 3: Post-migration

We’ve prepared detailed migration guides for migrating Mosaic macros:
Macro migration guides

Rebuilding macros using cloud equivalents


Once you've converted your pages 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.
You can find workaround suggestions for a range of macros here.
Icon of a white identity card inside a teal circle

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.
Learn more
Icon of a white paintbrush inside a purple circle

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!
Learn more
Icon of a white sticker with a rounded, peeling edge

How to adjust the corner radius of images

Make your Confluence images friendlier and more professional in seconds - it's easier than you think.
Learn more
Icon of a solid square in front of a square with dashed edges

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.
Learn more

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!
Learn more

Discover new (and better) ways to build pages in 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.
Explore Mosaic for Cloud
A screenshot of a Confluence Cloud page containing purple collapsible sections, a grey sidebar, and three teal cards in a row

Migration FAQs

Mosaic migration can be done with Atlassian’s CCMA via the “install-only” path, which means you just need to install the Mosaic Cloud app on your Confluence Cloud site, and no additional target-side changes are required.
There is a risk of data loss or formatting changes, especially for unsupported macros or complex formatting. We recommend that you perform a pre-migration analysis and a post-migration review. Please contact us if you need assistance with your migration plan.
We provide migration support through documentation, migration guidance, and direct assistance from our team to help you plan and migrate with confidence. For customers with more complex migrations, we also offer dedicated support through Customer Success, including migration consultation calls, implementation guidance, and help reviewing high-risk use cases. 
Mosaic's data residency and backup policies depend on the hosting region and Atlassian’s infrastructure. Contact us for specifics on your instance.
Yes, Mosaic AGC is available for government customers, with specific security and feature differences. Visit the Mosaic for AGC product page for more details.
A headshot of Customer Success Manager Abi Brown

Need help migrating with Mosaic?

I’m Abi, Kolekti’s Senior Customer Success Manager.

Whatever stage of your migration you're at, I’m here to support you. Book in some time with me below, and let’s discuss the specifics of your Mosaic migration.
Get in touch