How Nested Confluence Macros Are a Migration Challenge

We’ll look at how macros are nested, if and how that can be done in SharePoint as well, and how WikiTraccs approaches this during a migration.

How to Nest Macros in Confluence?

Let’s look at some examples.

If macros have a body, it is often possible to nest other macros in that body.

Here we have a Warning macro nested in an Info macro:

Edit Mode

View Mode

Here are Code Block macros nested in a table:

Edit Mode

View Mode

Here’s a more complex setup using the Column, Section, and Panel macros to put text and Code Block macros in a column layout:

Edit Mode

View Mode

How to Nest Web Parts in SharePoint Online?

It’s not possible.

In SharePoint Online, on modern SharePoint pages, you cannot nest web parts.

SharePoint web parts are put onto the page one after another; here a Text web part, followed by a Code Snippet web part:

It is technically impossible to put the Code Snippet web part into the Text web part.

This is a huge restriction compared to what you can do with Confluence macros.

What Does Missing Nesting in SharePoint Mean for Macro Migrations?

When trying to make nested macros compatible with SharePoint, here are the workarounds that can be applied:

• Converting nested macros to text so everything fits into a Text web part
• Moving nested macro content to another web part, e.g. moving the code macro to a separate Code Snippet web part

SharePoint also knows page sections, so there might be a chance one can get creative with those. But they are pretty heavyweight and cannot be nested as well.

How Does WikiTraccs Handle Nested Macros?

Let’s see the two de-nesting approaches in action with this Info macro that contains a Code Block macro:

Code Block Nested Inside Info Macro

View Mode

When encountering this in a migration, WikiTraccs does the following:

1. Convert the Info macro to a table in the SharePoint Text web part to make it look like in Confluence
2. Create a Code Snippet web part below the Text web part, move the code there
3. Create a note where the Code Block macro used to be about the de-nesting
4. Create yet another Text web part right above the Code Snippet web part marking the moved code snippet

The result looks like this (in SharePoint page edit mode):

Note: The dottet lines highlight the three involved web parts; those are not normally there in SharePOint and have been added for emphasis.

Above image also highlights another challenge when splitting content into multiple SharePint web parts. There is a pretty large gap between web parts that can look awkward. But there is nothing that can be done about that.

Wrap

Nested Confluence macros, but also macros in tables and those that are used inline, pose challenges for the migration.

There is only so much a migration tool like WikiTraccs can do, given the limitations that SharePoint Online has.

For the future, I hope and wish that Microsoft further expands the capabilities of SharePoint pages and web parts. I know that the third-party component backing the SharePoint text web part supports something like macros and I’d really like to see the Expand macro implemented in SharePoint.

• ←Previous
Next→