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

Buttons Migration Guide

Learn how to seamlessly migrate the Button Hyperlinks and Button Groups macros 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 Buttons macros from Confluence Data Center (DC) to Confluence Cloud.

In Confluence Data Center, Mosaic provides:
  • Button Hyperlink macro - Styled clickable buttons linking to pages, URLs, etc.
  • Button Group macro - Allows grouping multiple button hyperlinks together.

In Confluence Cloud, these are replaced by:
  • Button macro - Replicating the button hyperlink macro from DC with different styling options.
  • Button Group macro - Unchanged from DC apart from styling options.

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 Buttons, 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 buttons rely on the CSS Style Sheet Macro, be aware that this styling will not fully transfer to the Cloud Editor. Button styling is now set directly within the macro.
  1. Review pages for any custom CSS.
  2. Document where these are used, as manual changes may be required.

Migration - Migrating pages with Button Hyperlink and Button Group 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.
  • Button Hyperlink macros and Button Group macros are automatically converted to the Cloud Button and Button Group macros.


2. Review Migrated Pages


Once the migration is complete, open the migrated pages that contain Mosaic Button and Button Group macros.
Your Button Hyperlink and Button Group macros work as expected in the Legacy Editor in Cloud; however, styling applied using the CSS Style Sheet Macro may not be reflected, as this macro is unavailable in Cloud.

Need help migrating you Button macros?

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

Post-Migration - Upgrade to the Button and Button Groups Cloud Macros


1. Convert to the Cloud Editor


Before transforming your legacy Button Hyperlink and Button Group macros into Cloud Button and Button Group 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. 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.
  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 Button Hyperlink and Button Group macros are now automatically converted to Mosaic Button and Button Group Cloud Macros.


2. Review Styling


In DC, Button and Button Group macros often relied on the Mosaic CSS Style Sheet macros for styling. Due to editor limitations, the CSS Style Sheet does not migrate to Cloud, and button styling is done within the macro itself.
  • Review all Button macros in Cloud and apply styles individually with the macro editor options (colours, presets, icons). More information on styling buttons can be found here.
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