Macros provide dynamic content inside Confluence pages at the point where the macro is positioned. Users can insert macros into content when editing and can select from both default macros provided by Confluence and macros provided by your app.
You can use macros to build the following types of apps:
Macros can enable you to integrate with other systems, either owned by you or by accessing the public API of a known service. Your macro may integrate aspects of the service's experience within a Confluence page, or create an experience that accesses the service's API.
Examples include integration with:
You can use macros to create content that meets a specialized use case. This could be content that's difficult or impossible for users to create using default types of content available in the Confluence editor.
Macros can display content contained within the macro itself, known as the 'macro body'. For example, the chart macro that's built in to Confluence uses data in a table in the macro body to display a chart. Confluence renders the macro as a container in the editor, which users can add data to that the macro will display.
The main elements you need to build for a macro are:
Macros need to render within pages in order to be viewed. This is an easy first step to take after defining your macro following the getting started guide or the technical documentation.
When creating your macro you need to decide between a dynamic macro and a static macro. Dynamic macros are rendered asynchronously within an iframe. Static macros are rendered synchronously.
When your macro is defined, default Confluence features will allow users to create instances of your macro on a page using the macro browser and related keyboard shortcuts.
If you are integrating an external service with a unique URL pattern, you may want to consider implementing an autoconvert extension also which dynamically matches the URL when pasting and converts it to a macro instance.
When users add your macro to a page, there are three ways they can edit and specify properties for it:
The property panel can also be extended to provide a shortcut to changing macro properties.
You can create a page blueprint to complement your macro(s), as a shortcut to creating a new Confluence page. The page could have one or more instances of your macro on it, if it suits your macro's use case.
Page-level custom content can be a storage option for macros that store their data in Confluence, or as a way of creating a copy of an object stored in an external service. This leverages the benefit of integrating macros with Confluence search and navigation.
Get going by following our Getting started tutorial and referring to related documentation listed on the right hand side of this page.