This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Known Confluence Macros

This article is a resource where you can find information about known Confluence macros.

How WikiTraccs handles Confluence macros

WikiTraccs contains transformation rules for a range of Confluence macros. They are transformed on the fly and ideally the macro is replaced by something native to the SharePoint world.

If there is no SharePoint way of replacing a Confluence macro then WikiTraccs tries to find an approximation. But often there is just no equivalent for a Confluence macro. In those cases a text placeholder will be used to mark the spot where the macro has been in Confluence.

List of known macros

The following table shows macros that are explicitly known to WikiTraccs and how they are handled.

MacroSupport LevelMacro Transformation Details
StatusπŸ’šThe macro will be transformed to text with a color that tries to match the original (not so many choices here in SharePoint…).
NoformatπŸ’šThe “no formatting” content formatting will be mirrored in the SharePoint page.
Code BlockπŸ’š/🟑Code macros are transformed to SharePoint code web parts which provide comparable functionality. But if the code macro in Confluence is part of a table or any other nested structure then there is no 1:1 representation in SharePoint. The web part in this case will be replaced by a placeholder and the web part inserted at a top level place in the SharePoint page.
SharePoint Online Document (by Communardo)🟑The macro will be replaced by a link to the SharePoint document.
SharePoint Online List (by Communardo)🟑The macro will be replaced by a link to the SharePoint site containing the list; the link text contains the SharePoint list ID.
Profile Picture🟑The profile picture will be transformed like user @-mentions in the page (see section below for details).
User Profile🟑The user profile card will be transformed like user @-mentions in the page (see section below for details).
Enhanced Profile (by Communardo)🟑The user profile card will be transformed like user @-mentions in the page (see section below for details).
Jira Issue Link🟑The Jira macro will be replaced by a link to the Jira issue.
Jira Issue List🟑The Jira issue list will be converted to a static table showing links to Jira issues. If the table had multiple pages, a snapshot of only the first page is migrated to SharePoint. So, for a query that covers 1000 issues only the first 20 or so will be shown. A link to Jira is added to the SharePoint page so you can jump to Jira to see the live issue list.

Note that in Confluence Cloud this does only work with Interactive authentication; see Confluence Cloud Specialties for details.
Spreadsheet (by Elements)🟑The spreadsheet macro will be replaced by a link to the file attachment.
View File🟑The file card will be replaced by a link to the file attachment of the SharePoint page.
Office Powerpoint🟑The file card will be replaced by a link to the file attachment of the SharePoint page.
Office Word🟑The file card will be replaced by a link to the file attachment of the SharePoint page.
Office Excel🟑The file card will be replaced by a link to the file attachment of the SharePoint page.
Microsoft Stream Video🟑The file card will be replaced by a link to the video.
Panel, Info, Note, Warning, Tip🟑The macro will be replaced by a table rebuiding the macros’s structure as far as possible; this can introduce nested tables which will be a challenge for page layout (see section below for details on nested tables).
Expand🟑The expand functionality will be lost and the content remains expanded in the SharePoint page.
Gliffy🟑The Gliffy diagram will be replaced by an image of the diagram (that should be present in Confluence as page attachment); if there is no image a placeholder text will be used instead.
draw.io / draw.io board/sketch (by //Seibert/Media)🟑The draw.io diagram will be replaced by an image of the diagram (that should be present in Confluence as page attachment); if there is no image a placeholder text will be used instead.
Roadmap🟑Will be exported as image.
Widget Connector🟑The macro will be replaced by a link to the content it links to (for example a YouTube video), if there is such a link.
HTML🟑The HTML content from the macro will be transformed to a code web part in SharePoint; so the HTML is transformed to code and especially JavaScript will not be executed in the SharePoint page.
Tabs Container, Tabs Page (by Adaptavist)🟑This macro displays multiple tabs which is a challenge because SharePoint has no tabs. So the tabs are each one transformed to “normal” page content and all tabs are added one after another to the page.
Attachments🟑Note that the actual attachments of Confluence pages are always migrated to SharePoint. The Page Attachments macro is migrated as a static view of the macro at the time of migration. So the SharePoint page will show a static table with attachment links and some metadata.
Brikit Theme Press🟑The Brikit Theme Press is recognized by WikiTraccs. Brikit Theme Press layers will be converted to modern SharePoint page sections. Each SharePoint page section will have a number of columns that corresponds to the number of columns in the Brikit Theme Press layer. SharePoint can only have a maximum of three columns in a section, so WikiTraccs will create additional sections if there are more columns in the Brikit Theme Press layer. The content from Brikit Theme Press blocks will be added to the corresponding SharePoint section columns. Note: available as of WikiTraccs v1.16.0.
Page Tree🟑The Page Tree macro is migrated as a static view of the macro at the time of migration. The SharePoint page will show a static tree of page links.
Table of Contents🟑Migrated as a static view of the macro at the time of migration. The SharePoint page will show a static tree of page links.
Children Display🟑Migrated as a static view of the macro at the time of migration. The SharePoint page will show a static tree of page links.
Shared Block / Include Shared Block🟑Those macros are part of the Include Content app by Keysight Technologies. The shared block macro content is migrated as is, without surrounding text placeholders. The include shared block macro is now migrated as copy of the referenced “shared block” macro, instead of just a text placeholder. Note: available as of WikiTraccs v1.23.16.
MultiExcerpt (by Appfire)⏹
Table Filter (by StiltSoft)⏹️Filter functionality is lost, the table remains.
Excerpt⏹️
Single Cite (by Purde Software)⏹️The macro will be replaced by the citation content.
Table Chart⏹️The chart will be replaced by a table of the underlying data.
No Print⏹️The no-print functionality will be lost, the content remains.
Linchpin macrosπŸ”»/⏹There is no special handling built in for Linchpin macros, but they seem to transform fine to either text placeholders or macro body.
LivesearchπŸ”»
AnchorπŸ”»The anchor link will be removed, its text or content remains.
Content by LabelπŸ”»
Excerpt IncludeπŸ”»
Metadata News (by Communardo)πŸ”»
Metadata (by Communardo)πŸ”»
Recently UpdatedπŸ”»
Profile List (by Communardo)πŸ”»
Include PageπŸ”»
Team CalendarπŸ”»
Jira ChartπŸ”»
Task ReportπŸ”»
Content Report TableπŸ”»
Create from TemplateπŸ”»
Page PropertiesπŸ”»
Page Properties ReportπŸ”»
Page Tree SearchπŸ”»
Search ResultsπŸ”»
Create PageπŸ”»
Cite Summary (by Purde Software)πŸ”»
Blog PostsπŸ”»
Display Metadata (by Communardo)πŸ”»
Metadata Overview (by Communardo)πŸ”»
Metadata History (by Communardo)πŸ”»
Content by Metadata (by Communardo)πŸ”»
Other macrosπŸ”»/⏹️The macro will be replaced, either by a text placeholder or its body content.

Transformation types:

  • πŸ’š “nearly 1:1” - there is a SharePoint or HTML equivalent allowing to rebuild the functionality in SharePoint
  • 🟑 “changes in layout or functionality” - transformation with changes to layout or functionality; this is a transformation that is more than just a generic placeholder, but it does not fully meet the original macro functionality
  • ⏹️ “to macro body” - this works for macros that contain “richt text content” which is just normal wiki page content; this transformation type will replace the macro by its rich text content, thus kind of “unboxing” it
  • πŸ”» “to placeholder” - transforms to a non-functional placeholder text, showing the macro’s parameters

All macros not explicitly mentioned here are transformed to placeholders, so are either ⏹️ or πŸ”». When macros contain rich content then the macro is replaced by its rich content.

1 - 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.

What are macro placeholders?

They are text replacements for macros.

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 placeholder.

This generic macro transformation is applied to all macros that are not covered by an explicit transformation rule built-in to WikiTraccs.

How does a placeholder look?

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 placeholder?

WikiTraccs allows to apply custom text placeholders in generic macro transformations, using transformation templates.

You can use Handlebars templates to describe how the placeholder for a macro should look. Handlebars is a templating system commonly used in web development.

Let’s say we want to remove the placeholder text for the transformed div macro, just migrating its 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.

Where to put the transformation template?

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, 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.

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,…)

Transforming a single macro type

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:

  1. 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
  2. create a Handlebars template that describes how the custom placeholder should look
  3. save the Handlebars template in a file, in the Templates\Transformation folder
    • the filename follows the pattern MACRONAME.hbl where MACRONAME is the name of the macro
    • the file extension must be .hbl for WikiTraccs to recognize the file

Transforming multiple macro types

You can also put a special comment as first line into your .hbl 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?

The following variables are available in transformation templates:

VariableData TypeMeaning
Bodyn/athe macro body (if the macro has one)
HasBodybooleantrue, if the macro has a body; false otherwise
HasNoBodybooleantrue, if the macro has no body; false otherwise
Details.DisplayNametextmacro display name
TypeAsStringtext‘macro’ for macros, ‘ADF extension’ for ADF extensions, ‘unknown embedding’ otherwise
IsMacrobooleantrue, if the macro is a macro
IsAdfExtensionbooleantrue, if the ‘macro’ is an ADF extension (so, not really a macro, but covered by macro transformation nevertheless)
HasParametersbooleantrue, if the macro has parameters; false otherwise
ParameterCountnumberthe number of macro parameters
Parameterscollectionmacro 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

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.

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 .hbl 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

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.