Skip to main content
Kolekti home
Contact usBook a demo
🇪🇸 Barcelona, here we come! Catch us at Atlassian Team '25 Europe.
arrow icon

Tabs Macro Migration Guide

Learn how to seamlessly migrate the Mosaic Tabs macro from Confluence Data Center to Cloud with our step-by-step guide. Ensure a smooth transition with clear instructions and best practices.
Illustration of an open toolbox with floating icons representing various tools and features, including a rocket, chat bubble, checklist, user group, clock, and document, symbolising digital tools or resources for migration.
This step-by-step guide will walk you through the process of migrating Mosaic Tab 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:
  1. Click the Cog icon in the top-right corner to open Confluence Administration.
  2. Navigate to General Configuration.
  3. Under Mosaic Macros, click Mosaic Usage Tool.


2. Review Nesting


Confluence Cloud imposes stricter nesting (where one macro sits inside another) limits than Confluence DC. Make a note of any pages containing nested Mosaic Tabs, as these may need adjustments post-migration.
Pages with extensive nesting, especially when combining third-party and Mosaic macros, may not migrate correctly. If this applies to your content, contact us for tailored support.


3. Assess CSS Style Sheets


If your tabs rely on the CSS Style Sheet Macro, be aware that this styling may not fully transfer to the Cloud Editor.
  1. Review pages for any custom CSS.
  2. Document where these are used, as manual changes may be required pre- or post-migration.

Migration - Migrating Pages with Tabs


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 2025
  • Pages are imported into the new Cloud site using the Cloud Editor.
  • Mosaic Tab macros appear inside a Legacy Content macro, preserving most of their functionality.

2. Review Migrated Pages


Once the migration is complete, open the migrated pages that contain Mosaic Tabs macros.
  • Tabs should render properly within the Legacy Editor.
  • Pay special attention to pages using CSS; some styling may not display as expected.
NOTE: Nested tabs will not function correctly in Cloud if not wrapped in the Cloud Legacy macro. Contact us if you have nested tabs in your content for more tailored support.

Need help migrating your Tabs?

If you encounter issues with nested macros, unknown macros, or CSS styling, contact Mosaic support for assistance.
Mosaic Support arrow icon

Post-Migration - Upgrade to the Cloud Tabs Macro

After migration, Tabs will remain functional within the Legacy Editor (until January 2026). However, for the best editing experience and access to new features, we recommend converting them to the Cloud Tabs macro in the Cloud Editor.


1. Convert to the Cloud Editor


Before converting your legacy Tab macros into Cloud Tab macros, you must convert the page from the Legacy Editor to the Cloud Editor.
  1. 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.
  2. When prompted, click Preview page → Convert Page.
    Alternatively, you can choose to preview the page before converting.
  3. The page is converted to the Cloud Editor. All Mosaic Tabs macros are now wrapped in the Legacy Content macro.


2. Rebuild Tabs Using Cloud Tab Macros


Rebuild your tab structures using the Cloud version of Mosaic Tabs to take advantage of the modern Cloud Editor and CSS-free styling.
  • Refer to our Tabs documentation for step-by-step instructions on rebuilding your macros.
  • Enjoy features like simplified editing and consistent styling.


3. Replace Legacy CSS Styling


Page-level CSS will not migrate to Confluence Cloud. Instead:
  • Use the easy styling options available in the Mosaic Cloud Tabs macro.
  • Customise colours and backgrounds directly from the macro edit screen. No CSS required.
Side-by-side comparison of the Tabs macro in DC and once migrated to Cloud.
Example of Tabs macro in DC and once migrated to Cloud.
An icon of a target with a teal arrow in the bullseye

Need some help with migration? We're here!

Whatever your question or worry, our team of experts are here to give you clarity.
Speak to the Cloud Expertsarrow icon