How Do Confluence Macros Look in SharePoint?

The equivalent of Confluence macros in SharePoint are SharePoint web parts.

Confluence has a rich ecosystem of apps and macros. Microsoft is not there, yet, when it comes to providing a marketplace that brings the same to SharePoint Online.

We briefly examine what macros and web parts are, and then discuss the challenges and strategies for migrating macros to SharePoint.

What Is a Confluence Macro?

A Confluence macro is a piece of functionality that you can add to a Confluence wiki page.

Here’s the Info macro in edit and view mode:

The info macro’s job is to display text that is highlighted with a frame and potentially an icon.

Confluence administrators can install apps from the Atlassian Marketplace to add new macros to Confluence.

What Is a SharePoint Web Part?

A SharePoint web part is a piece of functionality that you can add to a SharePoint page.

Here’s the Text web part in edit and view mode:

SharePoint administrators can install apps from Microsoft AppSource to add new web parts to Confluence.

Migrating Macros to SharePoint Online Is Often Impossible

In most cases, it’s not possible to migrate Confluence macros to SharePoint.

Lack of Available Products

There often is no product available that can serve as a 1:1 replacement for the Confluence macro, either as an out-of-the-box solution or a as a commercial product.

Technical Differences

There are differences between macros and web parts that can make a 1:1 translation technically impossible, even if there was a vendor that tried to provide a 1:1 replacement. This will be covered in another article.

Effort Too High

If there were a product available that could bring a Confluence macro’s functionality to SharePoint, there would be several things that would need to be done:

1. Find the product
2. Evaluate if the product is a good replacement that covers the use cases
3. Purchase the product, or in the case of community solutions
4. Make the decision to help maintaining the community solution (one popular solution example is PnP Search)
5. Make WikiTraccs transform the macro to the product’s web part

Each of these steps might require a lot of work.

How to Migrate Confluence Macros to SharePoint Online?

Now that we have looked into the difficulties of migrating Confluence macros to SharePoint, let’s talk about solutions.

WikiTraccs uses the following approaches when bringing a Confluence macro to a SharePoint page:

1. One-to-one Transformation
2. Static Snapshot Transformation
3. Generic Macro Body Transformation
4. Text Placeholder

The following sections look into each of those approaches.

One-To-One Transformation

Some SharePoint web parts can replace the Confluence macro nearly one-to-one.

An example is the Code Block macro which will be transformed to a Code Snippet web part.

The expectation for a 1:1 transformation would be, that the SharePoint web part does things the same way as the Confluence macro.

There are not many of those transformations.

Static Snapshot Transformation

When WikiTraccs cannot find a 1:1 replacement for a Confluence macro in SharePoint, it might resort to taking a snapshot of the source macro.

Snapshot means, that it will migrate the current view of a macro to SharePoint, where the view will end up either as static page content or as a static image.

The Children Display Macro as an Example of Text Snapshots

One example is the Children Display macro. In the following sample, this macro shows the child pages for the current page, two levels deep:

Macro Edit View in Confluence

When migrating this to SharePoint, WikiTraccs takes a static snapshot of this view, and puts that into the migrated SharePoint page:

Snapshot View in SharePoint

Those links will work and point to the correct SharePoint pages. But the list won’t change when you add or remove pages, as it’s just a list of links in a SharePoint Text web part:

Text Web Part Edit Mode in SharePoint

In Confluence, when adding child pages to the current page, those pages will be shown by the Children Display macro. On the migrated page in SharePoint, the list is static.

The Draw.io Macro as an Example of Image Snapshots

Another popular example is the draw.io macro.

When migrating a draw.io macro to SharePoint, WikiTraccs uses the macro’s preview image and inserts that to the SharePoint page.

So, in SharePoint you’ve got a static image. The raw draw.io file is still around in SharePoint as page attachment, but still, you would have to take the file outside SharePoint to make changes to the diagram.

Generic Macro Body Transformation

WikiTraccs applies the Generic Macro Body transformation to macros that it doesn’t know (yet) or where there is no explicit transformation built-in.

Many Confluence macros act as frame for content. Let’s revisit the Info macro:

The body of the Info macro is the Lorem Ipsum text. When viewing the Confluence page, the Info macro applies formatting to its body - it draws a frame and shows an icon:

Another example is the Aura Background Content macro. This macro can be used to change the background of content, for example add a background color:

At the time of this writing, there was no explicit transformation built in to WikiTraccs for the Aura Background Content macro. So, WikiTraccs uses the default transformation for such macros: it migrates the macro body and surrounds it with text markers, indicating that there was a macro:

You’ll get used to that look after migrating a few pages.

A drawback of this approach is that it often loses styling and formatting. The benefit is that it preserves the actual content.

Text Placeholder

If WikiTraccs encounters a Confluence macro that has no body and thus no content that could be migrated, it replaces the macro with a text note.

Take the Stiltsoft Handy Button as example:

At the time of this writing there was not explicit transformation for this macro built into WikiTraccs. WikiTraccs transforms the macro to a text placeholder:

Here, the parameter output also shows the button caption and the link it points to. This would be a good candidate for being converted to a plain link by WikiTraccs.

Can WikiTraccs Transform a Macro Differently?

WikiTraccs continuously adds new macro transformations. Each transformation has to be hand-crafted. This is mostly driven by customer demand, so I’d like to hear about your high-priority macros.

When adding macro transformations to WikiTraccs, it is often not immediately clear how the result should look on a modern SharePoint page; or there are multiple ways of doing it.

Help me help you by suggesting a transformation and providing me with additional information. The most important part for me is that the desired result could be built manually by a user, in the browser, on a modern SharePoint page. For when a user can build it, WikiTraccs can do as well.

Please refer to the following blog post for more information on how features are added to WikiTraccs and which information helps getting it done: Can Feature ‘XYZ’ Be Added to WikiTraccs?