What about those Confluence Macros?

When referring to content migration it’s good to know which content is handled how, and macros are a big part of that.

Let’s start with something that has different meanings depending on context.


Page content for space owners might encompass everything on and around a Confluence page: text, macros, attachments, metadata and maybe also comments and permissions.

All those things would ideally be migrated 1:1 to SharePoint. Migrate, turn off Confluence, done.

As you might expect: it’s not that easy.

There are different angles to approach this topic and the different types of content one might expect to be migrated.

For today I want to highlight one type of content that needs awareness and preparation: macros.

What’s in a macro?

Confluence macros can be used to display different types of content.

Macros can aggregate content from other pages. Or they can show search results. They also allow entering unique content, like the Code or Info macro.

When WikiTraccs encounters macros it has different strategies to handle them:

  • replace by something similar in SharePoint
  • replace by a static representation (e.g. Page Attachments and Page Tree macros)
  • replace by its rich content (e.g. Expand macro)
  • replace by a mere text placeholder

Let’s look at an example page in edit mode:

Above Confluence page features text and three macros:

  1. the Info macro, containing text that I entered
  2. the Favorite Pages macro that shows my favorite pages
  3. the Lorem Ipsum macro that generates a random paragraph of text

Here’s how this page looks after having been migrated to SharePoint:

This looks pretty similar.

WikiTraccs, when migrating the page, retrieved text, the Info macro plus content and markers for the other two macros. And because Favorite Pages and Lorem Ipsum web parts don’t exist in SharePoint they are represented by a text placeholder in the resulting page.

Let’s now look at the page in Confluence without being in edit mode:

Confluence knows what Favorite Pages and Lorem Ipsum macros are supposed to do and shows additional, dynamically generated, content.

This, of course, is not possible to replicate in SharePoint.

Now what?

There’s not much WikiTraccs can do about macros not being available in SharePoint.

WikiTraccs already has special handling built-in for a handful of frequently used macros, like the Page Attachments and Page Tree macros.

For many macros you’ll see a placeholder in the migrated page.

Let’s zoom out for a moment.

It’s best to see this as a chance rather than an obstacle. SharePoint is different from Confluence. And as part of Microsoft 365 there is a good chance that something powerful can be built on the Microsoft-side of things.

And zooming in again here are some points for the migration-planning check list:

  • create an inventory of spaces and check which can be excluded from the migration
  • create an inventory of macros that are in use on Confluence pages in to-be-migrated spaces
  • evaluate how removing macros might affect legibility and understandability of pages
  • take a look at SharePoint standard web parts as well as community solutions like PnP Samples
  • think about how the content will be used in SharePoint; is it like an archive or will the content be worked on?
  • identify use cases that are affected by macros not being available in SharePoint anymore
  • re-think use cases to SharePoint / Microsoft 365 where needed (don’t forget about Microsoft Teams, Viva, the Power Platform etc.)

Something wholistic like a transformation workshop or down-to-earth requirements analysis might be in place. (My colleagues at Communardo can support with those.)

With WikiTraccs it’s free and easy to just test the migration. Looking at the results can spark meaningful discussions as well.

Get started today!

Give WikiTraccs a try and check out its transformation capabilities!

Quick start guide >>

Start today with WikiTraccs’ free Trial Version:

Download FREE WikiTraccs now

Or get in touch via email if you are interested in a demo. Give it 45 minutes and you’ll be up to speed on how WikiTraccs can help you.