Confluence Macros

The Confluence Builder extension may attempt to support various stock Confluence macros through the use of custom directives or roles. However, not all macros will have a markup defined for them with this extension. Some macros may not have a graceful way to be used in documentation, a stock macro has yet to have a directive/role created or the macro is provided by a third-party vendor.

Note

Typically, third-party vendor macros are not added into this extension. Exceptions may be made for free addons. However, this extension’s main goal is to focus on supporting stock macros.

If a stock Confluence macro does not have a directive/role created for it, users are welcome to submit a pull request to support the macro or create an issue outlining a desire for one. For developers wishing to support a third-party macro, it is recommended that developers create a custom extension providing support for this macro that can integrate with the Confluence Builder extension.

That all being said, users looking to use macros that do not have a directive/role define can add any custom macro using the raw directive. Consider the following examples. A user can add a “Cheese” macro using the following in a reStructuredText document:

.. raw:: confluence_storage

    <ac:structured-macro ac:name="cheese" ac:macro-id="5d87ef61-1fcf-4d30-8d3b-82305e13233a" />

Or create an “Info” macro in a Markdown document:

```{raw} confluence_storage
<ac:structured-macro ac:name="info" ac:macro-id="ecc1aad7-f2f5-4b75-86d1-786370e6d499">
    <ac:rich-text-body>
        <p>Test</p>
    </ac:rich-text-body>
</ac:structured-macro>
```

Try adding either of these example into a document to observe their results.

After trying out adding a raw macro from above, follow the steps in the next section to help add a custom macro to a document.

Steps

To add a custom macro available on a Confluence instance, perform the following steps:

  1. Creating a new page on the Confluence instance

  2. Add the specific macro to be captured on the page and saving

  3. Selecting the page’s option menu and selecting “View Storage format”

  4. Look for the ac:structured-macro tags in the storage format

  5. Copy the tags and place them into a raw-directive in the documentation