# Legacy content blocks

## [#](#understanding-legacy-content-in-confluence-cloud)Understanding legacy-content in Confluence Cloud

When content is migrated from Confluence Server/Data Center (DC) to Confluence Cloud, some parts of a page may be wrapped inside an internal macro called `legacy-content`. This wrapper is used when Cloud cannot safely convert the original storage format or macro structure into the new editor format.

Most often, this happens with:

* Nested macros / bodied macros (macros inside other macros)
* Complex layouts (tabs, accordions, sections, panels, etc.) that contain other macros
* Marketplace app macros whose Cloud behavior or storage format differs from DC

The \`legacy-content\` wrapper is designed to preserve data, but it can have side effects for any macro that happens to be inside it.

![Legacy Content Blocks in Confluence](https://help.gocapable.com/images/bc5dc297-a17d-4899-bb57-77365d9f11db.webp)

Refined Toolkit Tabs Macro after migration from Confluence DC

## [#](#why-legacy-content-appears)Why legacy-content appears

Typical triggers include:

* Migration of older storage formats
* Nested and bodied macros, such as Tabs (macros inside macros inside macros etc.)
* Macros from apps or custom integrations

This behavior is generic: it is not specific to any one vendor or macro type. Any macro can be affected if it ends up inside a \`legacy-content\` block.

## [#](#what-legacy-content-causes)What legacy-content causes

Once a part of the page is wrapped in \`legacy-content\`, anything inside that wrapper can be “hidden” from normal Cloud rendering and from many migration tools.

Symptoms you may see:

* Macro renders in Edit but not in View
* Migration tools miss inner macros
* Unexpected page fragments (duplicates: migrated macro outside + legacy version still inside)
* Broad impact across many macro types

Rule of thumb:

If a migrated macro works in Edit but not in View, it is very likely still wrapped in \`legacy-content\` or another complex nested container that Cloud cannot fully convert.

## [#](#how-to-resolve-legacy-content-blocks)How to resolve legacy-content blocks

There are two main approaches:

* [Manual cleanup (page-by-page)](https://help.refined.com/space/MIGRATETOOLKITCLOUD/5334139038/Preparing+your+nested+macros+for+Cloud)
* Automated cleanup using our macro migrators (recommended for scale)

Most teams use automation for the bulk of cases, plus manual cleanup for edge cases.

## [#](#option-1-manual-cleanup)Option 1: Manual cleanup

Use this when only a small number of pages are affected, or when you must preserve the exact layout.

1. Identify affected pages  
Look for macros that appear correct in Edit but break or disappear in View.
2. Edit the page and restructure the content  
Move the impacted macro out of the nested container.  
Rebuild the layout using native Confluence structures where possible.
3. Replace complex containers where feasible  
If the macro is nested inside a structure that triggers \`legacy-content\` (for example tabs/accordions/panels), consider replacing that structure with native Confluence alternatives.
4. Publish and verify  
Confirm the macro renders correctly in View.  
Remove any duplicates left behind.

## [#](#option-2-automated-cleanup-using-our-macro-migrators)Option 2: Automated cleanup using our macro migrators

For large migrations, manual fixes do not scale. Across all of our macro migrators, the same general strategy applies:

* Detect pages likely to produce \`legacy-content\` due to nested/bodied macros.
* Rewrite nested structures so macros are no longer trapped inside \`legacy-content\`.
* Replace complex legacy containers with native Confluence patterns (commonly native Expand macros).
* Migrate the inner macros once they are in a structure that Cloud can render reliably.

This approach is recommended when many pages are impacted and you need consistent results.

The following migrators extract body from the legacy-content blocks:

* Refined Tabs
* Mosaic Tabs
* Aura Tabs
* Vectors Tabs

## [#](#choosing-the-right-approach)Choosing the right approach

If layout can change (for example tabs to Expand): use automated tools.

If layout must be preserved exactly: apply manual cleanup for those pages, then migrate macros as needed.

## [#](#troubleshooting-checklist)Troubleshooting checklist

* Does the macro render in Edit but not in View?
* Is it nested inside another macro or complex container?
* Is the affected section wrapped in \`legacy-content\` after migration?
* Have you run an automated migrator pass designed to remove/replace legacy containers?
* After fixes, have you verified View mode and removed duplicates?

## [#](#summary)Summary

\`legacy-content\` most commonly comes from nested/bodied macro structures migrated from Confluence DC.

Any macro inside \`legacy-content\` may fail to render or be skipped by migrators.

You can resolve it either manually (restructure pages) or at scale using our macro migrators that remove legacy structures and replace them with native Confluence layouts such as Expand.