Skip to main content

Footnotes Macro Migration Guide

Learn how to seamlessly migrate the Mosaic Footnotes macro from Confluence Data Center to Cloud with our step-by-step guide.
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 Footnotes 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>General Configuration in the top-right corner to open Confluence Administration.
  2. Navigate to Mosaic Macros.
  3. Click Mosaic Usage Report.
  4. Click Start scan. The scan will begin.
  5. Once the scan is complete, click to Download Report.


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 Footnotes, 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 macros 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 Footnotes


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.

2. Review Migrated Pages


Once the migration is complete, open the migrated pages that contain Mosaic Footnote and Footnotes Display macros.
Your Footnotes work as expected in the Legacy Editor in Cloud; however, styling applied using the CSS Style Sheet Macro may not be reflected. If other macros are nested within Footnote macros, these will need checking; the same applies if Footnote macros are nested within other macros.

Post-Migration - Upgrade to the Footnote and Footnote Summary Cloud Macros

After migration, please review your Footnote macros, which will live in legacy macros that will be viewable but not directly editable. Follow the steps below to replace them with modern, cloud-friendly versions.

1. Rebuild DC Footnote macros using Cloud Footnote macros

Rebuild your Footnote macros using the Cloud version of the Footnote macro to take advantage of the modern Cloud Editor and CSS-free styling.
  • Refer to our Footnote documentation for step-by-step instructions on rebuilding your macros.
  • Enjoy features like simplified editing and consistent styling.
A headshot of Customer Success Manager Abi Brown

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.