1 - How Do Confluence Macros Look in SharePoint?
This article describes the ways in which WikiTraccs transforms Confluence macros to SharePoint content.
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:
- Find the product
- Evaluate if the product is a good replacement that covers the use cases
- Purchase the product, or in the case of community solutions
- Make the decision to help maintaining the community solution (one popular solution example is PnP Search)
- 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:
- One-to-one Transformation
- Static Snapshot Transformation
- Generic Macro Body Transformation
- Text Placeholder
The following sections look into each of those approaches.
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.
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.
Note
When creating a static snapshot of a macro, the snapshot includes what a user would see when looking at the page in a browser. If the macro supports paging though a long list of content in any way, only the content that is shown when opening the wiki page will be part of the snapshot.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.
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?
2 - Macro Placeholders and Transformation Templates
This article describes how macro placeholders work and how you can modify them with transformation templates.
Note: Macro transformation templates are available as of WikiTraccs v1.20.6.
Note: Macro transformation templates got more powerful with release v1.26.1. Make sure to use a current version.
What are Macro Placeholders?
Macro placeholders are text replacements for macros and look like this:
🚧👇 Replaced ‘xyz’ macro, its content follows below (atlassian-macro-output-type==‘INLINE’)
🚧☝️ End of content of replaced ‘xyz’ macro
When migrating wiki pages from Confluence to SharePoint, WikiTraccs has to transform macros to something that SharePoint understands.
If there is no equivalent to a macro in SharePoint (which is the regular case), WikiTraccs often applies a generic transformation that replaces the macro in SharePoint with a text note.
Macro Placeholder Example
Let’s take the div macro as example. It is part of Adaptavist’s Content Formatting Macros offering.
How does the div macro look before and after having been migrated to SharePoint?
The div macro allows to apply formatting to Confluence page content, like setting the text color.
The following configuration applies a blue text color to the macro content when the macro is shown on the Confluence page:
Macro in edit mode, applying the 'color:blue' CSS style to its content, plus some other things.
Macro in view mode, displaying blue text in the Confluence page.
When migrating this macro to SharePoint, WikiTraccs discards the macro container, pulls its content out, and puts that on the page. A text placeholder highlights that this happened:
So, the result of this transformation is:
- all content of the div macro has been migrated
- formatting is gone with the macro container
- a text placeholder highlights that a former div macro has been removed, but the content retained
Now, sometimes you want to get rid of that 🚧 placeholder text. You can create a custom placeholder to do that.
How to Create a Custom Macro Placeholder?
Advanced Topic
This and the following sections cover macro transformation templates which are designed to change how migrated pages look in SharePoint Online.
Originally, they were thought as a simple way to replace the default placeholder texts that WikiTraccs generates. But over time they got so powerful that WikiTraccs now by default uses a combination of built-in transformation logic and customizable transformation templates when adding support for new macros.
WikiTraccs allows to replace many of its built-in macro transformations using transformation templates. This can be used to replace generic macro placeholders with something different.
Note
There might be macros that are handled in such a way that their transformation logic cannot be replaced. One example is the code macro, which is transformed to a code snippet web part.You can use Handlebars templates to describe how the placeholder for a macro should look. Handlebars is a markup language and templating system commonly used in web development.
Note
Refer to the
Handlebars documentation to learn how Handlebars templates work. It is out of scope for this article to cover this.
Let’s say we want to remove the placeholder text for the transformed div macro, just migrating its body content.
The Handlebars template to do that looks like this:
{{!-- Don't add placeholder text, just render body --}}
{{Body}}
Some facts about above template:
{{Body}} is a variable, referencing the macro body; this tells WikiTraccs to just render the macro body, without additional placeholder text{{!-- --}} marks a comment in the template; this is ignored by WikiTraccs
Using above transformation template, the transformed macro looks like this in SharePoint:
The 🚧 note is now gone.
Custom transformation templates are stored as files in a folder.
When using WikiTraccs.GUI (the blue window), find WikiTraccs.GUI.exe and starting there, find the Templates\Transformation folder. Save your template file there.
When solely using WikiTraccs.Console (this most likely is not the case), find WikiTraccs.Console.exe and starting there, find the Templates\Transformation folder. Save your template file there.
The Transformation folder alreads contains files and should look like this (note that this can change in future WikiTraccs releases):
Each of those .hbs files contains a transformation template.
Note
The .hbs file extension is mandatory.The transformation templates can apply to either
- a single macro type (like div, or rw-ui-tabs-macro), OR
- multiple macro types (like english,belarusian,bulgarian,canadian-en,…)
When you want to transform a single macro type (like div), you save the transformation template in a file that carries the internal macro name in its filename and has the .hbs extension.
The file containing the transformation template for the div macro would thus be named div.hbs.
To reiterate, the steps to create a transformation template for a single macro type are:
- identify the internal macro name
- you can see macro names in the storage format XML
- note: for our div macro we see
ac:name="div" in the storage format XML
- create a Handlebars template that describes how the custom placeholder should look
- save the Handlebars template in a file, in the Templates\Transformation folder
- the filename follows the pattern MACRONAME.hbs where MACRONAME is the name of the macro
- the file extension must be .hbs for WikiTraccs to recognize the file
You can also put a special comment as first line into your .hbs file to apply the template to multiple macros, saving you the hassle to create identical files for each of those types.
Here is an example:
{{!-- applyto:english-us,english,belarusian,bulgarian,canadian-en,canadian-fr,catalan,chinese,croatian,czech,danish,dutch,estonian,finnish,french,german,greek,hindi,hungarian,icelandic,indonesian,irish,italian,japanese,korean,latvian,lithuanian,malay,maltese,norwegian-nb,norwegian,polish,portuguese,portuguese-br,romanian,russian,serbian,slovak,slovenian,spanish,swedish,thai,turkish,ukrainian,vietnamese --}}
This tells WikiTraccs to use the template for all the macros listed after the applyto: marker (internal macro names, separated by comma).
The filename doesn’t matter, as long as it has the .hbs ending.
Which Variables Are Available in Templates?
Note
Templates are written in the
Handlebars markup language that uses double and triple pairs of curly braces to encapsulate logic and variables. So, any of below variables might need to be enclosed in curly braces - look at existing templates or the Handlebars documentation on how the syntax looks exactly.
The following variables are available in transformation templates:
| Variable | Data Type | Meaning |
|---|
Body | n/a | the macro body (if the macro has one) |
HasBody | boolean | true, if the macro has a body |
HasNoBody | boolean | true, if the macro has no body |
Details.InternalName | text | internal macro name (for example “bgcolor”) |
Details.DisplayName | text | macro display name (for example “Background Color”) |
TypeAsString | text | ‘macro’ for macros, ‘ADF extension’ for ADF extensions, ‘unknown embedding’ otherwise |
IsMacro | boolean | true, if the macro is a macro |
IsMacroEmpty | boolean | true, if the macro is empty; a macro that only consists of whitespace and line breaks is considered empty as well; note that body-less macros may be considered not empty, if they are known to convert to content (like a date macro which seems empty, as it has no body content, but transforms to the current date and is therefore not empty) |
IsAdfExtension | boolean | true, if the ‘macro’ is an ADF extension (so, not really a macro, but covered by macro transformation nevertheless) |
HasParameters | boolean | true, if the macro has parameters |
HasNoParameters | boolean | true, if the macro has no parameters |
ParameterCount | number | the number of macro parameters |
Parameters | collection | macro parameters, if the macro has any; each parameter has a Name and Value property; there is also a Links property that is populated with links parsed from the parameters |
MacroXml | text | contains the raw macro XML as defined in the page’s storage format; note that you most likely need the triple brace syntax (like {{{MacroXml}}}) to work with that variable to prevent escaping |
@CanTransformToTable | boolean | null | internal indicator of WikiTraccs if the macro can be transformed to a table; sometimes set to false to prevent nested table structures, sometimes set to true if nesting is unlikely; might be null |
DefaultPlaceholder | n/a | generates the generic macro placeholder that is output by WikiTraccs if it doesn’t know a macro; this will output a placeholder text, macro parameter values, and the body (if there is any) |
RandomGuid1 | text | a randomly generated GUID value; the variable has the same value during one macro transformation, even if used in multiple places of the template file; this can be useful if you need a random GUID at multiple places in the same template; there is also RandomGuid2 and RandomGuid3 available, providing up to 3 random GUIDs |
Parameter | object | special variable granting access to macro parameters; see section Accessing Macro Parameters below |
The following commands are available as well:
| Command | Meaning |
|---|
{{Exit}} | Cancels processing of the current transformation template; can be used to fall back to the built-in transformation logic of WikiTraccs |
{{RemoveMacro}} | Removes the current macro without replacement |
There are also helper functions available like String.Equal (which can be used to compare two text values for equality). Those are sometimes used by WikiTraccs’ own templates and are documented via their usage in those templates.
WikiTraccs brings some transformation template files along. In the Templates/Transformation folder, have a look at the unknown.hbs.sample file for an advanced usage example, or any of the other files.
Note
WikiTraccs more and more transitions to using transformation templates instead of hard-coded macro transformation logic.Working with Macro Parameters
Macro parameters can be accessed via the Parameter variable.
For example the value of the macro parameter title is available via Parameter.title.Value. The parameter name (here title) is always written lowercase, even if the original macro parameter is not.
To get the value of a macro parameter (as text), you use the Parameter.paramname.Value syntax.
To get the raw XML representation of a macro parameter (as text), you use the Parameter.paramname.Xml syntax.
If the macro parameter contains links, those are accessible via the Parameter.paramname.Links collection. Each of the links can have a Title and Href property. The unknown.hbs.sample sample transformation template file shows how to enumerate links.
Sometimes WikiTraccs injects additional macro parameters mainly for internal use in its own transformation templates:
Parameter.wikitraccs-targetreference - added (for example) to Excerpt Include and Multiexcerpt include macros; this parameter contains an ac:link element, pointing to the page the snippet is included from; it’s used to generate a link to the source page
Multi-pass transformation has been introduced for internal use by WikiTraccs but might pose useful for you as well. Nevertheless, it’s tailored to WikiTraccs’ immediate needs and you’ll probably hit limitations.
Macro transformation is done in three phases for each macro:
- prebuiltin
- builtin
- postbuiltin
Prebuiltin can be used to decorate a macro before the built-in transformation logic kicks in.
Builtin executes the built-in transformation logic for a macro. Macro transformation templates can replace this logic.
Postbuiltin is used internally by WikiTraccs where a macro is not yet fully transformed in the builtin stage, but will be in postbuiltin.
Macro transformation templates by default are applied in the builtin stage (and replace the builtin transformation logic), unless marked otherwise.
A transformation template can be marked for a specific stage like this:
expand[prebuiltin].hbs - executed in prebuiltin stageexcerpt-include[postbuiltin].hbs - executed in postbuiltin stageexcerpt.hbs - no marker, builtin stage by default
Templates for SharePoint Web Parts
Have a look at the Convert Macros to SharePoint Web Parts to learn about web part generation.
Templates that generate web parts have a specific structure and the <div data-wikitraccs-webpart-template="true"> element plays a key role. It acts as marker for WikiTraccs to trigger web part generation.
A macro transformation template completely replaces the internal transformation logic of WikiTraccs for that macro. If you want some of the results of the internal logic back, you need to replicate it in the macro template.
There are limits to what can be done in macro transformation templates. It will not be possible to replace all of WikiTracc’s internal transformation logic with a custom transformation template.
Only one transformation template per macro template can be registered. Registering multiple templates per macro type leads to undefined behavior.
Troubleshooting
If your template is not recognized check for the following issues:
- the template file is in the wrong folder
- the template file doesn’t have the .hbs file ending
- the filename doesn’t have the right pattern
- the macro is already handled by a built-in transformation rule and thus no generic placeholder is being generated (note: there is nothing you can do about that; please get in touch and give feedback)
- the template is malformed
Note
When starting WikiTraccs.GUI it will process all transformation templates it can find and log the result to the common log files. If there is an error, it will show an error dialog.
So, after editing template files, start WikiTraccs.GUI and if nothing pops up, at least the syntax is correct.
Note: this behavior is new as of release v1.26.1.
Check the console log output or common log files to see if WikiTraccs loads your template.
This is how the log looks if a template could be successfully loaded:
Found 3 transformation template files in folder '<path>/Templates/Transformation', will handle one by one: ch.bitvoodoo.confluence.plugins.language.hbs div.hbs rw-ui-tabs-macro.hbs
Trying to load transformation template from file 'Templates/Transformation/div.hbs'
Compiling and registering transformation template for 'div'
Any issues should be visible here as well. You can also look at the logs to learn about the path WikiTraccs loads templates from, if you are unsure where to put them.
2.1 - Macro Transformation Template Samples
This article shows sample templates.
Note: Macro transformation templates got more powerful with release v1.26.1. Make sure to use a current version.
Note
Macro transformation templates replace internal transformation logic of WikiTraccs.Simple Body Replacement
Remove Macros without Body
The following template replaces the macro by its body content, for a list of macros. If the macro has no body, it will be removed.
{{!-- applyto:style,auibuttongroup,auibutton,div,bgcolor,alert,align,bibtex-reference,bibtex-display,center,clickable,auidialog,span,fancy-bullets,footnote,display-footnotes,highlight,auihorizontalnav,htmlcomment,img,table,tr,th,td,thead,tbody,iframe,latex-formatting,ol,li,ul,lozenge,auimessage,p,pre,privacy-policy,privacy-mark,auiprogress,auiprogressstepstatic,roundrect,search-box,span,tooltip,strike,copyright,reg-tm,sm,tm, --}}
{{#if HasBody}}
{{Body}}
{{else}}
{{RemoveMacro}}
{{/if}}
This preserves the macro body, even if it only consists of whitespace or line breaks.
Remove Macros without Body, or with Empty Body
If you want to remove such empty macro bodies as well, use the following approach, which also removes macros with empty body:
{{!-- applyto:style,auibuttongroup,auibutton,div,bgcolor,alert,align,bibtex-reference,bibtex-display,center,clickable,auidialog,span,fancy-bullets,footnote,display-footnotes,highlight,auihorizontalnav,htmlcomment,img,table,tr,th,td,thead,tbody,iframe,latex-formatting,ol,li,ul,lozenge,auimessage,p,pre,privacy-policy,privacy-mark,auiprogress,auiprogressstepstatic,roundrect,search-box,span,tooltip,strike,copyright,reg-tm,sm,tm, --}}
{{#if HasBody}}
{{#unless IsMacroEmpty}}
{{Body}}
{{else}}
{{RemoveMacro}}
{{/unless}}
{{else}}
{{RemoveMacro}}
{{/if}}
