Macros are how you take XWiki's functionality to the next level. They can be used to:

• Display content in a more visually appealing manner or highlight important information
• Embed documents, such as PDF or Office files or display diagrams
• Show the relations between XWiki pages and improve navigation
• Display media, such as videos and audio

All Pro Macros are dedicated for formatting content on any XWiki instance, no matter the usecase. For Confluence Migration specific macros please visit our Confluence Migration Toolkit. 

List of Macros

• Button
• Contributors
• Content Report Table
• Excerpt
• Excerpt Include
• Expand
• MsStream
• Panel
• Profile Picture
• Show-if / Hide-if
• Status
• Tab and Tab-group
• Taglist
• Team
• Recently Updated
• User List
• User Profile
• View Files

Inserting a macro

To insert a macro you should edit the page:

• Type "/" in your editor and type the name of the macro
• For XWiki versions 14.x and older, click on the "+" icon from the editor
• Select the macro from the list
• Fill in the needed parameters
• Click "Submit"

Editing a macro

Macros can be edited by double clicking on the macro in the visual editor. Alternatively, you can edit the syntax of the macro by going to the page's source. The supported parameters, as well as the syntax, are detailed in the Documentation tab for each macro.

FAQ

1. Can the User or Team macros display the people who have access to a page?

Not directly. The Team  Pro Macro is designed to display avatars of team members. It can filter users by tags, a specified list of users, scope, and external authentication. Its requireExternalAuth parameter can be used to restrict the displayed users to those found through LDAP or OpenID Connect Authenticator. However, this parameter is about the user source. It does not calculate or display who has effective view, edit, or comment rights on the current page.

The Contributors macro available in the Confluence Migration Toolkit can display the people who contributed to a page. This is useful for documentation ownership and maintenance visibility, but this is different from calculating effective access rights.

For checking permissions, administrators can use XWiki’s rights management interface. XWiki lets administrators manage rights at wiki, space, and page level, including rights for users and groups.

For a broader overview of configured rights, you can use the Admin Tools Application, a contributed extension*. Its Show Rights feature lists specific rights configured across the wiki, spaces, and pages.

For a more modern administration interface, you can also use Admin Tools Pro. Its Security section includes dedicated views for group rights, user rights, transfer rights, and user rights on a page. This can be a useful option when administrators need to investigate access issues in a more guided interface.

Like Admin Tools, Page Rights Viewer Application is a contributed extension*. It shows the actual rights applied to a page, as well as persistent rights inherited from parent pages. It also provides an Actual Rights macro that can display the effective rights table for the current page or another selected page.

So, while Pro Macros do not currently provide a simple “who can read this page?” widget for non-admin users, XWiki offers several options for reviewing and managing access rights depending on the level of detail you need.

2. Which file types can be edited using the View File macro, and does this depend on Collabora?

The View File macro and the Collabora Connector serve different purposes within XWiki.

We provide the View File macro to display attachments directly inside an XWiki page. It allows embedding Office or PDF documents and can show thumbnails for various attachment types, including images and videos. The file needs to be attached to the page beforehand. An office server must be configured for the View File macro to function as expected.

For editing capabilities, we rely on an office integration. The Collabora Connector Application integrates Collabora Online within XWiki and enables viewing, editing, and real-time collaboration on office attachments using the WOPI protocol.

The exact formats available depend on the configured Collabora server and its version. For this reason, we recommend reviewing the compatibility details of your Collabora deployment before defining a file-format policy.

3. After migrating from Confluence, how can Pro Macros help teams clean up and improve imported pages?

Pro Macros and Confluence Bridge Macros are included in the Confluence Migration Toolkit.

They are included alongside other applications to support the migration process and help teams improve how content is structured, displayed, and maintained after it has been imported.

After importing Confluence content with the Confluence Migration Toolkit, teams often need to review repeated text, standardize page layouts, improve the readability of long pages, and create clearer overview pages. Pro Macros can support that work in several ways:

• Excerpt and Excerpt Include can define reusable sections of content.
• Panel can create consistent visual blocks for notes, warnings, migration notices, or important guidance.
• Expand can keep optional detail available without making every page feel too long.
• Tab and Tab Group can separate alternative instructions, versions, or environments.
• Status can add visible lifecycle labels, such as draft, reviewed, or deprecated.
• Content Report Table can create structured reports based on tags and spaces.
• Recently Updated can surface recent activity across pages, comments, blog posts, or attachments.
• Contributors can make content ownership and maintenance more visible.
• View File can embed supporting documents directly in a page.

The goal is not simply to reproduce the original Confluence knowknowledge nizationion. It is to help teams turn imported content into an XWiki knowledge base that is clearer to navigate and easier to maintain.

4. What is the difference between the Confluence Migration Toolkit and Pro Macros in a migration project?

The Confluence Migration Toolkit is a package of migration-related applications designed to support different stages of a Confluence-to-XWiki project.

It includes the Confluence Migrator Pro together with a set of supporting applications designed to cover the full migration process. This package already includes Pro Macros, along with Confluence Bridge Macros, Confluence Bridge Macros, Task Manager Pro, Diagram Pro, Calendar Pro, and support.

The Confluence Migrator Pro focuses specifically on importing and organizing Confluence content. It can migrate pages, hi navigages, history, nion, commentsvigation, comments, users, groups, groups, permissions, attachments, macros, metadata, tags, favorites, tags (labels), and favorites. In order to properly import and display more than 140 macros from Confluence, the Confluence Bridge Macros are essential and they are present in the Confluence Migration Toolkit package. 

Pro Macros are part of the toolkit, but can be used in any XWiki instance, in spite of the source of the content (be it imported from Confluence, office files, or a new wiki system). Pro Macros provide a collection of macros for content formatting, reuse, reporting, display, navigation, and page presentation. They are used to improve how content looks and behaves once it is in XWiki.

In practical terms:

• Use the Confluence Migration Toolkit as the complete solution to prepare, migrate, review, and fix content during a migration project.
• Use Pro Macros, included in that toolkit, to structure and improve the resulting XWiki pages during and after the migration.

5. How can the Panel macro help recreate or improve Confluence-style info boxes, warnings, and custom panels?

The Panel macro displays content in a visual container. It can be configured with a title, background colour, width, height, CSS classes, border colour, border style, border width, border radius, title background colour, and title text colour.

The box macros (info, warning, note, success) and custom panel macros from Confluence are converted into XWiki page content during the migration step executed via the Confluence Migrator Pro, present in the Confluence Migration Toolkit. The resulting page will look almost identical to the original Confluence page. See below an example of a page with boxes migrated from Confluence to XWiki:

6. Can users see an excerpt included on another page if they don’t have access to the original page?

By default, no.

In XWiki, the Excerpt macro includes a parameter called allowUnprivilegedInclude. This parameter controls whether an excerpt can be displayed to users who do not have view rights on the page where the excerpt is defined.

By default, this parameter is set to false, which means that excerpts respect the access rights of their source page. Users who cannot view the original page will not see the excerpt when it is included elsewhere.

If allowUnprivilegedInclude is explicitly enabled, the excerpt can be displayed even to users who do not have access to the source page. This can make the excerpt visible to a broader audience than the source page itself.

This option should be used with caution. Before enabling it, teams should ensure that the excerpted content is appropriate for a wider audience and verify the behavior within their specific rights configuration.

This is particularly important in XWiki, where access rights can be defined at the wiki, space, and page levels.

7. What Pro Macros are especially helpful when creating technical documentation?

The most relevant Pro Macros for technical documentation depend on how your content is structured and maintained. However, several macros are commonly used to improve clarity, reuse, and navigation across documentation spaces.

For content reuse and consistency across multiple pages, the Excerpt and Excerpt Include macros allow you to define reusable sections of content and include them wherever needed. This helps reduce duplication and ensures that shared information remains consistent across the documentation.

When structuring long procedures or organizing optional or contextual information, macros such as Expand, Tab, and Tab Group are particularly useful. They help keep pages readable by hiding secondary details or separating content into logical sections, such as different environments or product versions.

To highlight important information and document content status, the Panel and Status macros are commonly used. They are well suited for displaying warnings, prerequisites, notes, or indicating whether content is in a draft, reviewed, or deprecated state.

For creating overview pages and supporting content maintenance, macros like Content Report Table, Recently Updated, and Contributors provide valuable insights. They can help teams monitor page activity and see who has edited or commented on selected content.

When it comes to displaying user and team information, the Team, User List, and User Profile macros can be used to display relevant people and team information within documentation pages.

To embed supporting materials directly in the documentation, the View File macro allows you to display attached documents, such as PDFs or office files, within a page.

Finally, for navigation and calls to action, the Button and Taglist macros can guide users through documentation or highlight related content.

For example, a technical documentation team might use Panels to highlight safety warnings, Excerpts to reuse standard prerequisites, Tabs to separate instructions by operating system or version, and Content Report Tables to generate documentation indexes based on tags.

8. What is the difference between using a standard XWiki macro and using a Pro Macro?

Standard macros are provided by XWiki Standard or by community extensions. They cover many general content and presentation needs. Community-contributed macros* are typically maintained on a best-effort basis, depending on the availability and priorities of their contributors.

Pro Macros are a professionally supported collection of macros available through the XWiki Store. They provide an additional set of features for content reuse, formatting, user and team display, reports, page navigation, status display, file display, and more. As Pro applications, they are maintained by XWiki SAS and include regular security and functionality updates, maintenance, and quick professional support.

The distinction is therefore mainly about the extension package and support model. Both standard macros and Pro Macros are used inside XWiki instances. Pro Macros add a supported set of additional capabilities that can be useful when teams need more structured documentation patterns or migration cleanup tools.