We are building out our library of bundled macros. Prior to release, this is driven mostly by what we require. Let us know what would be useful to you.

Longer-term, the intention is that you can build on these macros yourself.

Include Version Macro

This macro is similar to the include page macro, but allows you to select a specific version of the page to include.

This is great for reports and proposals, because you can create a space that consists only of boilerplate, and if you’re lucky your report will not be much more than a combination of includes.

The problem with this macro is that people may not be aware that the page they are editing is being included in several other pages, and may make inappropriate edits. This macro, along with the includes report macro, lets you easily control that.

By default, when including a page using this macro it will default to the number of the latest version. There is an additional option Latest, which simply tracks the latest version. When this option is used it becomes identical to the standard Include Page macro.

include version macro config

You can use the macro browser preview functionality to view the results of including the different versions.

Converting Pages

If you have many instances of the include page macro on a page, it would be painful to manually update them. A REST endpoint is included which will convert all instances of include page to include version. The version number is specified to be the current latest version, so the page contents should be identical (until one of the includes is modified).

You can easily hook up this endpoint using a web item:

convert includes web item

The condition code is the Current page contains particular macros sample, with cheese changed to include.

The link address is:


Once configured it will appear as below, but only on those pages that contain the include page macro.

convert includes disp

Includes Report Macro

This macro is used in conjunction with the include version macro. It will show you which includes have later versions, with links to the diffs so that you can easily see what version you want to update to, if any.

It also provides a button to Update All, which will update all includes to the version number of the latest version (check the diffs first to make sure this is what you want). When used it will create and save a new version of the current page - you can always roll it back if it wasn’t the result you wanted.

includes report view

To display this macro best you could put it in a panel macro. If you are writing reports for customers, you probably don’t want them to see this information - so put the panel in a NoPrint user macro.

Example source:

includes report source

CQL Search Macro

This macro executes the provided CQL query and returns the results as links to pages. It can useful to show the results of complex queries on pages, or labels etc.

Various improvements are expected in this macro in the near future.

Markdown Macro

This macro displays Markdown from a URL location, which could we a web address or a file location. To use a file location you should prepend your file path with file://

Typically you would want to include some Markdown from a Gist or from Github on a page.

In GitHub you need to click on the Raw button to get the URL to the original Markdown file.

github raw

If you want to display markdown from another Atlassian product, for example Bitbucket Server then the macro will automatically detect if you have an application link setup for the url you have entered and use it to retrieve the content.

This macro only supports the CommonMark specification of Markdown which means different flavours of the Markdown specification may not render correctly.

Currency Converter Macro

This simple macro converts an amount of money to multiple target currencies based on the latest exchange rate. It uses YAHOO! finance to get up-to-date exchange rate data.

The macro gets the latest exchange rate each time you refresh the macro or open the page.

To get the latest exchange rate just provide valid amount and select the From and To currencies:

currency converter

Imagine you want to show the photos of group members in a page. This macro will help you to achieve this easily. It shows profile photos of group members in tabular format for a group. Add the macro in a page, provide the group name and number of profile pictures you want to see in a row. That’s all!

mugshot gallery
The macro shows first 200 members of a group returned by confluence API.

Lock Content Macro

Let’s say as a page author you want to add a page status or information and do not want the information to be removed or modified by specific users or groups. This is not achievable straight away as Confluence does not support the concept of partial restrictions. Lock Content Macro helps you achieve this by restricting users or groups editing its content. Add the user name in Restricted Users or group in Restricted Groups you want to restrict. That’s all. The user or the users in group won’t be able to edit content of the macro. In the following screenshot all the users in "painters" group and user "dali" won’t be able to modify the content of the Lock Content Macro.

lock content
The macro does not restrict Confluence administrators and space administrators from editing the contents.
There are few cases where the macro cannot restrict user from updating its contents. For an example using API it is possible to change a page content. It is advisable to use this macro considering this cases.

For how-to questions please ask on Atlassian Answers where there is a very active community. Adaptavist staff are also likely to respond there.

Ask a question about ScriptRunner for JIRA, for for Bitbucket Server, or for Confluence.