This page is an extension of the page about the Confluence storage format. This page describes the XML used to define specific Confluence macros – those that are shipped with Confluence. For each macro, we define the macro name, parameter names, and accepted parameter values.
This information is intended for advanced users who need to interpret and edit the underlying markup for a Confluence page.
On this page:
Anchor macro
Allows you to link to a specific part of a page.
Macro name: anchor
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
(Unnamed in wiki markup) | Yes | (None) | The name of the anchor. |
Example:
<ac:macro ac:name="anchor"> <ac:default-parameter>here</ac:default-parameter> </ac:macro>
Attachments macro
Displays a list of attachments on a given page.
Macro name: attachments
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
old | No | false | Available values:
|
patterns | No | (None) | A comma-separated list of regular expressions, used to filter the attachments by file name. Note that the parameter values must be regular expressions. For example:
|
sortBy | No | date | Available values:
|
page | No | The page on which the macro exists. | Page name, used to display attachments from another page. |
sortOrder | No | The default sort order is determined by the
| Available values:
|
labels | No | (None) | A comma-separated list of labels. Confluence will show only attachments that have all the labels specified. (The match is an AND, not an OR.) |
upload | No | false | Determines whether the list of attachments will include options allowing users to browse for, and attach, new files. |
Example:
<ac:macro ac:name="attachments"> <ac:parameter ac:name="old">false</ac:parameter> <ac:parameter ac:name="patterns">.*png,.*jpg</ac:parameter> <ac:parameter ac:name="sortBy">name</ac:parameter> <ac:parameter ac:name="page">My page about chocolate</ac:parameter> <ac:parameter ac:name="sortOrder">descending</ac:parameter> <ac:parameter ac:name="labels">chocolate,cookies</ac:parameter> <ac:parameter ac:name="upload">false</ac:parameter> </ac:macro>
Blog Posts macro
Lists the most recent news items in the space.
Macro name: blog-posts
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
content | No | entire | Available values:
|
spaces | No | @self | One or more space keys, separated by a comma or a space.
Special values:
When specifying a personal space, remember to use the tilde (~) sign in front of the username, such as |
author | No | (None) | One or more usernames, separated by commas. |
time | No | (None) | Available values:
For example,
|
reverse | No | false | A value of true changes the sort order. |
sort | No | creation | Available values:
|
max | No | 15 | The maximum number of results to be displayed. |
label | No | (None) | One or more label values, separated by a comma or a space.
|
Example:
<ac:macro ac:name="blog-posts"> <ac:parameter ac:name="content">titles</ac:parameter> <ac:parameter ac:name="spaces">@self,ds</ac:parameter> <ac:parameter ac:name="author">jsmith</ac:parameter> <ac:parameter ac:name="time">4w</ac:parameter> <ac:parameter ac:name="reverse">true</ac:parameter> <ac:parameter ac:name="sort">creation</ac:parameter> <ac:parameter ac:name="max">10</ac:parameter> <ac:parameter ac:name="label">chocolate,cookies</ac:parameter> </ac:macro>
Change-History macro
Displays a history of updates made to a page.
Macro name: change-history
Macro body: None.
Parameters: None.
Example:
<ac:macro ac:name="change-history"/>
Chart macro
Displays a chart based on tabular data.
Macro name: chart
Macro body: Accepts rich text, consisting of tables that hold the chart's data.
This macro recognises a large number of parameters, listed here by type for convenience.
Chart type parameters
These parameters determine the type of chart to display and how the chart looks.
Parameter | Required | Default | Description |
---|---|---|---|
type | No | pie | The type of chart to display. XY charts have numerical x- and y-axes. The x values may optionally be time-based. See the Available values:
|
orientation | No | vertical | The display orientation. Applies to area, bar and line charts. Available values:
|
3D | No | false | Show in three dimensions. Applies to area, bar and line charts. |
stacked | No | false | Stacked values. Applies to area and bar charts. |
showShapes | No | true | Applies to line charts. Shapes are shown at each data point. |
opacity | No |
| A percentage value between 0 (transparent) and 100 (opaque) that determines how opaque the foreground areas and bars are. |
Chart display parameters
Parameter | Required | Default | Description |
---|---|---|---|
width | No | 300 | The width of the chart in pixels. |
height | No | 300 | The height of the chart in pixels. |
dataDisplay | No | false | Determines whether to display the body of the macro, consisting of the data table. By default, the chart data table is not displayed. Available values:
|
imageFormat | No | png | The image format to be used for the chart. Available values:
|
Chart title and label parameters
Parameter | Required | Default | Description |
---|---|---|---|
title | No | (None) | The title of the chart. |
subTitle | No | (None) | A subtitle for the chart. |
xLabel | No | (None) | The label for the x-axis (domain). |
yLabel | No | (None) | The label for the y-axis (range). |
legend | No | false | Determines whether to show a legend (key) for the chart. |
Chart data parameters
The data for the chart is taken from tables found in the macro body. The parameters below control how this data is interpreted. By default, numeric and date values are interpreted according to the Confluence global default language (locale) formats. If conversion fails, other languages defined in Confluence will be tried. You can specify additional conversion options using the parameters below.
Parameter | Required | Default | Description |
---|---|---|---|
tables | No | All first level tables | You can supply a comma-separated list of table IDs and/or table numbers (starting at 1) contained within the body of the macro that will be used as the data for the chart. If data tables are embedded in other tables, then table selection will be required. This occurs when more complex formatting is done (for example using section and column macros). |
columns | No | All columns | You can supply a comma-separated list of column labels and/or column titles and/or column numbers for tables used for chart data. This applies to all tables processed. Columns are enumerated starting at 1. Column label is the text for the column in the header row. Column title is the HTML title attribute for the column in the header row. |
dataOrientation | No | horizontal | The content orientation. By default, the data tables will be interpreted as columns (horizontally) representing domain and x values. Available values:
|
timeSeries | No | false | If ' |
dateFormat | No | Confluence language defined date formats | For time series data, the date format allows for additional customisation of the conversion of data to date values. If a dateFormat is specified, it will be the first format used to interpret date values. Specify a format that matches the time series data. See simple date format. |
timePeriod | No | day | The time period for time series data. Defines the granularity of how the data is interpreted. Available values: |
language | No | (None) | Use in combination with the Available values are the two-character ISO 639-1 alpha-2 codes. |
country | No | (None) | Use in combination with the language parameter to form a locale. Valid values are the two-character ISO 3166 codes. |
forgive | No | true | Determines whether the macro will forgive (allow) some data formatting errors. Available values:
|
Chart colour parameters
Colours are specified using hexadecimal notation or HTML colour names.
Parameter | Required | Default | Description |
---|---|---|---|
bgColor | No | White | Background colour of the chart. |
borderColor | No | No border | Colour of the border around the chart. |
colors | No | A comma-separated list of colours used to customise the colours of categories, sections, and series. |
Chart axis parameters
Depending on the chart type, the range and domain axis may be customised. These values are automatically generated based on the data but can be overridden by specifying one or more more of these parameters.
Parameter | Required | Default | Description |
---|---|---|---|
rangeAxisLowerBound | No | (None) | Minimum value for the range axis. |
rangeAxisUpperBound | No | (None) | Maximum value for the range axis. |
rangeAxisTickUnit | No | (None) | Range axis units between axis tick marks. |
rangeAxisLabelAngle | No | (None) | Angle for the range axis label in degrees. |
domainAxisLowerBound | No | (None) | Only applies to XY plots. Domain axis lower bound. For a date axis, this value must be expressed in the date format specified by the dateFormat parameter. |
domainAxisUpperBound | No | (None) | Only applies to XY plots. Domain axis upper bound. For a date axis, this value must be expressed in the date format specified by the dateFormat parameter. |
domainAxisTickUnit | No | (None) | Only applies to XY plots. Domain axis units between axis tick marks. For a date axis, this value represents a count of the units specified in the timePeriod parameter. The timePeriod unit can be overridden by specifying a trailing character: y (years), M (months), d (days), h (hours), m (minutes), s (seconds), u (milliseconds). |
domainAxisLabelAngle | No | (None) | Only applies to XY plots. The angle for the domain axis label, in degrees. |
categoryLabelPosition | No | (None) | Placement of the axis label text for categories. Available values:
|
dateTickMarkPosition | No | start | Placement of the date tick mark. Available values:
|
Pie chart Parameters
Parameter | Required | Default | Description |
---|---|---|---|
pieSectionLabel | No | Show only the pie section key value | Formatof pie section labels. The format uses a string with special replacement variables:
Example 1: To display something like 'Independent = 20': %0% = %1%
%0% (%2%) |
pieSectionExplode | No | No exploded sections | A comma-separated list of pie keys that are to be shown exploded. Note: requires jFreeChart version 1.0.3 or higher. |
Chart attachment parameters
These are advanced options that can be used for chart versioning, to enable automation and to improve performance. Use these options carefully! Normally, the chart image is regenerated each time the page is displayed. These options allow for the generated image to be saved as an attachment and have subsequent access to re-use the attachment. This can be useful especially when combined with the Cache plugin to improve performance. Depending on the options chosen, chart images can be versioned for historical purposes.
Parameter | Required | Default | Description |
---|---|---|---|
attachment | No | (None) | The name and location where the chart image will be saved as an attachment. The user must be authorised to add attachments to the page specified. Available syntax for this parameter:
|
attachmentVersion | No | new | Defines the the versioning mechanism for saved charts. Available values:
|
attachmentComment | No | (None) | Comment used for a saved chart attachment. |
thumbnail | No | false | If |
Example:
Below is a simple example of a pie chart. See more examples in Storage Format Examples for Chart Macro.
<ac:macro ac:name="chart"> <ac:parameter ac:name="title">Fish Sold</ac:parameter> <ac:parameter ac:name="type">pie</ac:parameter> <ac:rich-text-body> <table> <tbody> <tr> <th> <p>Fish Type</p> </th> <th> <p>2004</p> </th> <th> <p>2005</p> </th> </tr> <tr> <th> <p>Herring</p> </th> <td> <p>9,500</p> </td> <td> <p>8,300</p> </td> </tr> <tr> <th> <p>Salmon</p> </th> <td> <p>2,900</p> </td> <td> <p>4,200</p> </td> </tr> <tr> <th> <p>Tuna</p> </th> <td> <p>1,500</p> </td> <td> <p>1,500</p> </td> </tr> </tbody> </table> </ac:rich-text-body> </ac:macro>
Cheese macro
Displays the words "I like cheese!"
Macro name: cheese
Macro body: None.
Parameters: None
Example:
<ac:macro ac:name="cheese"/>
Children Display macro
Displays the children and descendants of the current page.
Macro name: children
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
reverse | No | false | Reverses the sort order in the list of child pages. Use this parameter in conjunction with the sort parameter described below. A value of true will change the sort order from ascending to descending. |
sort | No | Manual if the pages have been manually reordered, otherwise alphabeticalby page title | Determines the sort order of the list of child pages. Available values:
|
style | No | Bullet list | A heading style to be applied to the list of child pages. Available values: |
page | No | The page that contains the macro | The name of the parent page. The macro will display the children of the specified page. To specify a page in a different space, use a space key followed by a colon. For example: If the value of this parameter is a forward slash ( |
excerpt | No | false | If true , Confluence will display any excerpts that are defined on the child pages. The excerpts must be defined via an Excerpt macro. |
first | No | (None) | The maximum number of child pages to be displayed (at the top level). For example, if the value of this parameter is 99 , the macro will display the first 99 pages at the top level. It will also display their children, as determined by the depth and all parameters |
depth | No | (None) | The number of levels of child pages to display. For example, if the value is 2, the macro will display 2 levels of child pages. |
all | No | false | If |
Example:
<p> <ac:macro ac:name="children"> <ac:parameter ac:name="reverse">true</ac:parameter> <ac:parameter ac:name="sort">creation</ac:parameter> <ac:parameter ac:name="style">h4</ac:parameter> <ac:parameter ac:name="page">Home</ac:parameter> <ac:parameter ac:name="excerpt">true</ac:parameter> <ac:parameter ac:name="first">99</ac:parameter> <ac:parameter ac:name="depth">2</ac:parameter> <ac:parameter ac:name="all">true</ac:parameter> </ac:macro> </p>
Code Block macro
Displays code in your document with the appropriate syntax highlighting.
Macro name: code
Macro body: Accepts plain text.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
title | No | (None) | Adds a title to the code macro box. |
theme | No | Confluence | Specifies the colour scheme used for displaying your code. Many of these themes are based on the default colour schemes of popular integrated development environments (IDEs). The default theme is Available themes:
|
linenumbers | No | false | If If |
language | No | java | Specifies the language (or environment) for syntax highlighting.
|
firstline | No | 1 | When linenumbers is true , this value defines the number of the first line of code. |
collapse | No | false | If If |
Example:
The following example shows all parameters and a body:
<ac:macro ac:name="code"> <ac:parameter ac:name="title">This is my title</ac:parameter> <ac:parameter ac:name="theme">FadeToGrey</ac:parameter> <ac:parameter ac:name="linenumbers">true</ac:parameter> <ac:parameter ac:name="language">html/xml</ac:parameter> <ac:parameter ac:name="firstline">0001</ac:parameter> <ac:parameter ac:name="collapse">true</ac:parameter> <ac:plain-text-body><![CDATA[<b>This is my code</b>]]></ac:plain-text-body> </ac:macro>
Below are three examples of the Code Block macro with various optional parameters used.
Description | Markup | What you will get |
---|---|---|
Code block macro with a body and no optional parameters | <ac:macro ac:name="code"> <ac:plain-text-body><![CDATA[this is my code]]></ac:plain-text-body> </ac:macro> | this is my code |
Code block macro with a body and the optional language parameter defined | <ac:macro ac:name="code"> <ac:parameter ac:name="language">html/xml</ac:parameter> <ac:plain-text-body><![CDATA[this is my code]]></ac:plain-text-body> </ac:macro> | this is my code |
Code block macro with a body and optional title, line numbers and language parameters defined | <ac:macro ac:name="code"> <ac:parameter ac:name="title">This is my title</ac:parameter> <ac:parameter ac:name="linenumbers">true</ac:parameter> <ac:parameter ac:name="language">html/xml</ac:parameter> <ac:plain-text-body><![CDATA[this is my code]]></ac:plain-text-body></ac:macro> | This is my title this is my code |
Column macro
Used with the Section macro to define columns on a page. See Working with page layouts and columns and sections.
Macro name: column
Macro body: Accepts rich text.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
| No | 100% of the page width, divided equally by the number of columns in the section. | The width of the column. Can be specified either in pixels (for example, 400px ) or as a percentage of the available page width (for example, 50% ). |
Example:
<ac:macro ac:name="column"> <ac:parameter ac:name="width">100px</ac:parameter> <ac:rich-text-body> <p>This is the content of <strong>column 1</strong>.</p> </ac:rich-text-body> </ac:macro>
Content by Label macro
Displays a list of content associated with specific labels.
Macro name: contentbylabel
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
spaces | No | @all | Filters the results by space. The macro will display only the pages and other content types which belong to the space(s) you specify here.
Special values:
When specifying a personal space, remember to use the tilde (~) sign in front of the username, such as |
author | No | (None) | Filters the results by author. The macro will display only the pages and other content types which are written or updated by the author(s) you specify here. jsmith,jbrown To include content from one user, but exclude from another user: |
title | No | (None) | Adds a heading to the list. |
showLabels | No | true | Determines whether to display the matching labels in the list of results. |
reverse | No | false | Use this parameter in conjunction with the sort parameter. Set reverse=true to change the sort from ascending to descending. This parameter is ignored if the sort parameter is not specified. |
sort | No | modified | Determines how the results are sorted. To change the sort order from ascending to descending, use the reverse parameter described above. If this parameter is not specified, the sort order defaults to descending order based on the last modification date. Values:
|
max | No | 15 | Determines the maximum number of results to be displayed. Note that the results are sorted first, and then the maximum parameter is applied. |
excerpt | No | false | If this parameter is set to true , the macro displays an excerpt from each page listed in the results. Note that you must define the excerpts on each of those pages, by adding the Excerpt macro to each page. If a particular page does not have an excerpt defined, then the Content by Label macro will not attempt to show an excerpt for that page. The Content by Label macro will show only the first few lines of the excerpt for each page. |
labels | Yes | (None) | Use this parameter to filter the results by label. The macro will display only the pages and other content types which are tagged with the label(s) you specify here. See also the operator parameter.You can specify one or more label values, separated by a comma or a space.
|
showSpace | No | true | Determines whether to display the spaces in the list of results. |
type | No | All | Filters the restults by content type. The macro will display only the content of the type you specify here. You can specify one or more types, separated by a comma or a space. To exclude content of a given content type, put a minus sign (-) immediately in front of that content type. For example: If you specify a content type of Available values:
|
operator | No | OR | The operator to apply to the supplied lists of labels. By default, a page with any of the non-prefixed labels (that is, labels without a plus (+) or minus (-) sign immediately preceding it) will be listed. If you specify a value of AND , only pages with all of the supplied non-prefixed labels will be listed. Note that this parameter only modifies the behaviour of the 'Label(s)' parameter and only affects label values without a plus (+) or minus (-) sign prefix. To avoid confusion or unexpected results, we recommend that you do not use the operator parameter in conjunction with any label values prefixed with '+' or '-' signs. |
Example:
<ac:macro ac:name="contentbylabel"> <ac:parameter ac:name="spaces">@personal,@self</ac:parameter> <ac:parameter ac:name="author">admin,smaddox</ac:parameter> <ac:parameter ac:name="title">My labelled pages</ac:parameter> <ac:parameter ac:name="showLabels">false</ac:parameter> <ac:parameter ac:name="reverse">true</ac:parameter> <ac:parameter ac:name="sort">creation</ac:parameter> <ac:parameter ac:name="max">10</ac:parameter> <ac:parameter ac:name="excerpt">true</ac:parameter> <ac:parameter ac:name="labels">chocolate,cake</ac:parameter> <ac:parameter ac:name="showSpace">false</ac:parameter> <ac:parameter ac:name="type">page</ac:parameter> <ac:parameter ac:name="operator">AND</ac:parameter> </ac:macro>
Content by User macro
Displays a list of the content items that have been created by a specified Confluence user.
Macro name: content-by-user
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
(Unnamed in wiki markup) | Yes | (None) | The Confluence username for the person whose content you wish to display |
Example:
<ac:macro ac:name="content-by-user"> <ac:default-parameter>jsmith</ac:default-parameter> </ac:macro>
Content Report Table macro
Displays a set of pages and blog posts in tabular format, based on the labels specified in the macro parameters.
Macro name: content-report-table
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
spaces | No | (None) | This parameter is required. Specify one or more labels, separated by a comma. The macro will display only the content tagged with the label(s) specified here. |
labels | Yes | (None) | Specify one or more space keys, separated by a comma or a space. The macro will display only the content which belongs to the space(s) specified here. When specifying a personal space, remember to use the tilde (~) sign in front of the username, such as ~jbloggs or ~jbloggs@example.com . |
maxResults | No | (None) | Define the maximum number of pages that the macro will show in a single set of results. If there are more pages to be shown, the macro will display a link labelled 'Find more results'. |
Example:
<ac:macro ac:name="content-report-table"> <ac:parameter ac:name="spaces">DOC</ac:parameter> <ac:parameter ac:name="labels">LDAP</ac:parameter> <ac:parameter ac:name="analytics-key">meeting-notes</ac:parameter> <ac:parameter ac:name="maxResults">5</ac:parameter> </ac:macro>
Contributors macro
Displays a list of Confluence users who have made a contribution of some type to a page.
Macro name: contributors
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
| No | (None) | Limits the number of contributors displayed in the list. |
| No | Current space | Specifies the space key of the Confluence space to search. Space keys are case sensitive. You can specify one or more space keys or special values, separated by commas. |
| No |
| Reverses the order of contributors in the list. Must be used in conjunction with the |
scope | No | The specified page only | Specifies additional pages to include when generating the list of contributors. Available values:
|
| No | (None) | Limits the list of contributors to those who created the specified labels on a page. You can specify one or more labels, separated by commas. |
showPages | No |
| If the value is true, the macro will display a list of the pages used to generate the list of contributors. |
noneFoundMessage | No | "No contributors found for:" (and a summary of selected parameter values) | Any message given here will override the default message that is displayed when no contributors are found. |
| No | false | Determines whether the macro will show the number of times each person made a contribution. |
contentType | No | Both pages and blog posts | Restricts the content type that the macro will use when generating the list of contributors. Available values:
|
include | No | authors | Filters by either the type of contribution made to a page (and optionally its descendant pages), or the watches on the page. Contribution types are:
You can specify one or more contribution types, separated by commas. |
mode | No | inline | Determines how the list of contributors is formatted:
|
showAnonymous | No | false | Determines whether to include those who contributed anonymously to a page. |
order | No | count | Specifies the criteria used to sort contributors. Sort criteria are:
|
page | No | The current page | Specifies the page to use when generating the list of contributors. If |
showLastTime | No | false | Determines whether to show the last time each person made a contribution. |
publishDate | No | (None)e | Specifies the publication date for a blog post. The date format required is: YYYY/MM/DD. |
Example:
This example specifies a content type of blog posts:
<ac:macro ac:name="contributors"> <ac:parameter ac:name="limit">10</ac:parameter> <ac:parameter ac:name="spaces">ds,@personal</ac:parameter> <ac:parameter ac:name="reverse">true</ac:parameter> <ac:parameter ac:name="labels">chocolate,cake</ac:parameter> <ac:parameter ac:name="showPages">true</ac:parameter> <ac:parameter ac:name="noneFoundMessage">Oh dear, no contributors found</ac:parameter> <ac:parameter ac:name="showCount">true</ac:parameter> <ac:parameter ac:name="contentType">blogposts</ac:parameter> <ac:parameter ac:name="include">authors,comments,labels,watches</ac:parameter> <ac:parameter ac:name="mode">list</ac:parameter> <ac:parameter ac:name="showAnonymous">true</ac:parameter> <ac:parameter ac:name="order">update</ac:parameter> <ac:parameter ac:name="showLastTime">true</ac:parameter> <ac:parameter ac:name="publishDate">2012/06/30</ac:parameter> </ac:macro>
This example specifies a content type of pages:
<ac:macro ac:name="contributors"> <ac:parameter ac:name="limit">10</ac:parameter> <ac:parameter ac:name="spaces">ds,@personal</ac:parameter> <ac:parameter ac:name="reverse">true</ac:parameter> <ac:parameter ac:name="scope">descendants</ac:parameter> <ac:parameter ac:name="labels">chocolate,cake</ac:parameter> <ac:parameter ac:name="showPages">true</ac:parameter> <ac:parameter ac:name="noneFoundMessage">Oh dear, no contributors found</ac:parameter> <ac:parameter ac:name="showCount">true</ac:parameter> <ac:parameter ac:name="contentType">pages</ac:parameter> <ac:parameter ac:name="include">authors,comments,labels,watches</ac:parameter> <ac:parameter ac:name="mode">list</ac:parameter> <ac:parameter ac:name="showAnonymous">true</ac:parameter> <ac:parameter ac:name="order">update</ac:parameter> <ac:parameter ac:name="page">ds:Advanced Topics</ac:parameter> <ac:parameter ac:name="showLastTime">true</ac:parameter> </ac:macro>
Contributors Summary macro
Displays a table of contribution-based statistics for a set of pages.
Macro name: contributors-summary
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
| No | (None) | Limits the number of contributors or pages displayed in the table. |
| No | Current space | Specifies the space key of the Confluence space to search. Space keys are case sensitive. You can specify one or more space keys or special values, separated by commas. |
| No |
| Reverses the order of items in the table. Must be used in conjunction with the |
showAnonymous | No | false | Determines whether to include those who contributed anonymously to a page. |
scope | No | The specified page only | Specifies additional pages to include when generating the list of contributors. Available values:
|
order | No | edits | Sets the criterion used for sorting items in the table. Available values:
|
page | No | The current page | A page title. Specifies the page to use when generating the list of contributors. If |
| No | (None) | Limits contribution-based statistics to the specified labels only. You can specify one or more labels, separated by commas. |
columns | No |
| Determines the columns that should appear in the table. The statistics or type of information presented depends on the Available values:
You can specify one or more columns, separated by commas. |
groupby | No | contributors | Specifies the basis for grouping contribution-based statistics:
|
contentType | No | Both pages and blog posts | Restricts the content type that the macro will use when generating the list of contributors. Available values:
|
showZeroCounts | No | false | Determines whether contributors or pages are included for which the calculated statistic is zero. |
publishDate | No | (None) | Specifies the publication date for a blog post. The date format required is: YYYY/MM/DD. |
Example:
This example specifies a content type of blog posts:
<ac:macro ac:name="contributors-summary"> <ac:parameter ac:name="limit">10</ac:parameter> <ac:parameter ac:name="spaces">ds,@personal</ac:parameter> <ac:parameter ac:name="reverse">true</ac:parameter> <ac:parameter ac:name="showAnonymous">true</ac:parameter> <ac:parameter ac:name="order">update</ac:parameter> <ac:parameter ac:name="labels">chocolate,cake</ac:parameter> <ac:parameter ac:name="columns">edits,comments,labels,lastupdate</ac:parameter> <ac:parameter ac:name="groupby">pages</ac:parameter> <ac:parameter ac:name="contentType">blogposts</ac:parameter> <ac:parameter ac:name="showZeroCounts">true</ac:parameter> <ac:parameter ac:name="publishDate">2012/06/07</ac:parameter> </ac:macro>
This example specifies a content type of pages:
<ac:macro ac:name="contributors-summary"> <ac:parameter ac:name="limit">10</ac:parameter> <ac:parameter ac:name="spaces">ds,@personal</ac:parameter> <ac:parameter ac:name="reverse">true</ac:parameter> <ac:parameter ac:name="showAnonymous">true</ac:parameter> <ac:parameter ac:name="scope">descendants</ac:parameter> <ac:parameter ac:name="order">update</ac:parameter> <ac:parameter ac:name="page">ds:Advanced Topics</ac:parameter> <ac:parameter ac:name="labels">chocolate,cake</ac:parameter> <ac:parameter ac:name="columns">edits,comments,labels,lastupdate</ac:parameter> <ac:parameter ac:name="groupby">pages</ac:parameter> <ac:parameter ac:name="contentType">pages</ac:parameter> <ac:parameter ac:name="showZeroCounts">true</ac:parameter> </ac:macro>
Create from Template macro
Creates a page from a given template.
Macro name: create-from-template
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
| Required for user-created templates | (None) | The ID of a user-created template. This is the unique identifier that Confluence assigns when you create a template. For example, 299630593 . To find the ID of a template, edit the template and look at the URL in your browser. The template ID is given in the URL parameter named entityId . |
blueprintModuleCompleteKey | Required for blueprints | (None) | The qualified name of the add-on that defines the blueprint (for example, com.atlassian.confluence.plugins.confluence-shared-files-plugin:file-list-blueprint ). |
| Yes | (None) | The ID of a user-created template (for example, 299630593 ) or the qualified name of the add-on that defines the blueprint (for example, com.atlassian.confluence.plugins.confluence-shared-files-plugin:file-list-blueprint ). |
buttonLabel | Yes | 'Create from Template' | The description that people will seeing when viewing this macro on the page. |
spaceKey | Yes | The space where the current page is located | The unique space identifier, to determine where the new page will be created when someone uses this macro to create a page. |
Title | No | (None) | The title for pages created using this macro. You can include @currentDate , @spaceName and @spaceKey variables in the title. This title will override any title specified in a blueprint template. |
Example:
This example specifies a user-created template:
<ac:macro ac:name="create-from-template"> <ac:parameter ac:name="templateId">299630593</ac:parameter> <ac:parameter ac:name="buttonLabel">Blitz test</ac:parameter> <ac:parameter ac:name="spaceKey">DOCTHEME</ac:parameter> <ac:parameter ac:name="templateName">299630593</ac:parameter> </ac:macro>
This example uses a blueprint:
<ac:macro ac:name="create-from-template"> <ac:parameter ac:name="blueprintModuleCompleteKey">com.atlassian.confluence.plugins.confluence-shared-files-plugin:file-list-blueprint</ac:parameter> <ac:parameter ac:name="buttonLabel">Shared files</ac:parameter> <ac:parameter ac:name="spaceKey">DOCTHEME</ac:parameter> <ac:parameter ac:name="templateName">com.atlassian.confluence.plugins.confluence-shared-files-plugin:file-list-blueprint</ac:parameter> </ac:macro>
Create Space Button macro
Displays a create space button linked to the create space page.
Macro name: create-space-button
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
size | No | large | Determines the size of the 'create space' icon displayed. Available values:
|
width | No | Natural size of icon (1:1 pixel ratio) | The width of the icon to be displayed, specified in pixels. Confluence will stretch or shrink the width of the icon to the number of pixels specified. Note: This parameter is not available via the macro browser. |
height | No | Natural size of icon (1:1 pixel ratio) | The height of the icon to be displayed, specified in pixels. Confluence will stretch or shrink the height of the icon to the number of pixels specified. Note: This parameter is not available via the macro browser. |
Example:
<ac:macro ac:name="create-space-button"> <ac:parameter ac:name="size">small</ac:parameter> </ac:macro>
Excerpt Include macro
Allows you to display an excerpt from another page within the current page.
Macro name: excerpt-include
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
(Unnamed in wiki markup) | Yes | (None.) | The name of the page that contains the excerpt to be displayed. To include an excerpt from a page in another space, type the space key followed by a colon (:) and the page name, like this:
Note: The ability to include excerpts from other spaces is available only in Confluence 4.3.2 and later. In earlier versions of Confluence, the Excerpt Include macro does not work across spaces. Use the Include Page macro instead. |
nopanel | No | False | Determines whether Confluence will display a panal around the excerpted content. The panel includes the title of the page containing the excerpt, and the border of the panel. By default, the panel and title are shown. |
Example:
<ac:macro ac:name="excerpt-include"> <ac:parameter ac:name="nopanel">true</ac:parameter> <ac:default-parameter>My page name</ac:default-parameter> </ac:macro>
Excerpt macro
Define a part of a page as the page's 'excerpt' which can then be displayed in another page.
Macro name: excerpt
Macro body: Accepts rich text.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
hidden | No | False | Determines whether the content of the Excerpt macro body is displayed on the page that contains the Excerpt macro. Note that this option affects only the page that contains the Excerpt macro. It does not affect any pages where the content is reused. |
atlassian-macro-output-type | No | BLOCK | Determines whether the content of the Excerpt macro body is displayed on a new line or inline. Available values:
Note that this option affects only the page that contains the Excerpt macro. It does not affect any pages where the content is reused. |
Example:
<ac:macro ac:name="excerpt"> <ac:parameter ac:name="hidden">true</ac:parameter> <ac:parameter ac:name="atlassian-macro-output-type">BLOCK</ac:parameter> <ac:rich-text-body> <p>This is the <strong>text</strong> I want to reuse in other pages. This text is inside an Excerpt macro.</p> </ac:rich-text-body> </ac:macro>
Expand macro
Displays an expandable/collapsible section of text.
Macro name: expand
Macro body: Accepts rich text.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
(Unnamed in wiki markup) | No | Click here to expand... | Text that will be displayed on the line that people can click to expand the hidden text. |
Example:
<ac:macro ac:name="expand"> <ac:default-parameter>This is my message</ac:default-parameter> <ac:rich-text-body> <p>This text is <em>hidden</em> until you expand it.</p> </ac:rich-text-body> </ac:macro>
Favourite Pages macro
Displays a list of your favourite pages.
Macro name: favpages
Macro body: None.
Parameters: None.
Example:
<ac:macro ac:name="favpages"/>
Gadget macro
Allows you to add Confluence gadgets to pages or blog posts.
Macro name: gadget
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
| No | 450 pixels | The width of the gadget, using one of the following conventions:
|
border | No | true | Determines whether Confluence will draw a border around the gadget. |
url | Yes | (none.) | This is the location of the gadget specification (XML file). |
preferences | No | (Gadget-dependent.) | Specific property settings that are particular to each gadget. |
A note about editing a gadget's properties (preferences) in markup: It is possible to edit the values of these properties directly in the wiki markup or storage format. However, this will allow the entry of invalid values. If a gadget property supports a certain set of values, the macro browser will restrict the user to selecting only valid values for that property. For that reason, we recommend that you use the macro browser to edit a gadget's properties.
Example:
This example shows the Confluence Page gadget:
<ac:macro ac:name="gadget"> <ac:parameter ac:name="width">500</ac:parameter> <ac:parameter ac:name="border">false</ac:parameter> <ac:parameter ac:name="url">rest/gadgets/1.0/g/com.atlassian.confluence.plugins.gadgets:confluence-page-gadget/gadgets/confluence-page-gadget.xml</ac:parameter> <ac:parameter ac:name="preferences">spaceName=Documentation&spaceKey=DOC&quickfind-space=Documentation&pageId=753666&pageName=Documentation%20Home&quickfind-page=Documentation%20Home&isEditable=true&isConfigured=true&refresh=15&showLink=false</ac:parameter> </ac:macro>
This example shows the Confluence News gadget:
<ac:macro ac:name="gadget"> <ac:parameter ac:name="url">rest/gadgets/1.0/g/com.atlassian.confluence.plugins.gadgets:confluence-news-gadget/gadgets/confluence-news-gadget.xml</ac:parameter> <ac:parameter ac:name="preferences"/> </ac:macro>
Gallery macro
Forms a thumbnail gallery of all images attached to a page.
Macro name: gallery
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
title | No | (None) | Specify a title to be displayed above your gallery of pictures. |
reverse | No | Not specified. Sort order is ascending. | Used in combination with the Available values:
|
sort | No | None. The sort order is unspecified and therefore unpredictable. | Specify an attribute to sort the images by. Sort order is ascending, unless you specify the Available values:
|
page | No | If no page is specified, the gallery macro displays the images attached to the page on which the macro is used. | Specify the title of the page which contains the images you want displayed. You can specify more than one page name, separated by commas. To specify a page in a different space, use the following syntax: SPACEKEY:Page title. |
includeLabel | No | None. The images are not filtered by label. | The gallery will include only those pictures that have the specified label. If you wish to enter more than one label, separate the labels with commas. Confluence will show only images that have all the labels specified. (The match is an AND, not an OR.) For information on labelling the attachments, see Adding Labels. |
excludeLabel | No | No exclusions. The gallery will include all the pictures on the page. | The gallery will ignore any pictures that have the specified label. You can specify more than one label, separated by commas. For information on labelling the attachments, see Adding Labels. |
columns | No | 4 | Specify the number of columns for the table that forms the gallery. |
| No | No exclusions. Include all the pictures on the page. | Specify images by file name. The gallery will ignore any images specified. You can specify more than one image, separated by commas. |
| No | Include all the pictures on the page. | If you specifically include one or more pictures, the gallery will show only those pictures. You can specify more than one picture, separated by commas. |
Example:
<ac:macro ac:name="gallery"> <ac:parameter ac:name="title">My holiday pictures</ac:parameter> <ac:parameter ac:name="reverse">true</ac:parameter> <ac:parameter ac:name="sort">size</ac:parameter> <ac:parameter ac:name="page">My page1, ds:Welcome to Confluence</ac:parameter> <ac:parameter ac:name="excludeLabel">badlabel1, badlabel2</ac:parameter> <ac:parameter ac:name="columns">3</ac:parameter> <ac:parameter ac:name="exclude">badpicture.png</ac:parameter> </ac:macro>
Global Reports macro
Displays a list of links to global reports within a table.
Macro name: global-reports
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
width | No | 99% | Specify the width of the table in which the links are displayed, as a percentage of the window width. |
Example:
<ac:macro ac:name="global-reports"> <ac:parameter ac:name="width">50%</ac:parameter> </ac:macro>
HTML Include macro
Includes the content of an external HTML file into a Confluence page.
Macro name: html-include
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
url | Yes | (None) | Specify a URL of the content to be included into your Confluence page. |
Example:
<ac:macro ac:name="html-include"> <ac:parameter ac:name="url">http://www.example.com</ac:parameter> </ac:macro>
HTML macro
Renders your specified HTML code within the current page.
Macro name: html
Macro body: Text, consisting of HTML code.
Parameters: None.
Example:
<ac:macro ac:name="html"> <ac:plain-text-body><![CDATA[<a href="http://www.atlassian.com">Click here</a> to see the <b>Atlassian</b> website.]]></ac:plain-text-body> </ac:macro>
IM Presence macro
Displays graphically when a contact is online.
Macro name: im
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
showid | No |
| Determines whether the macro shows or hides the user ID of the contact. Available values:
|
service | Yes | Not specified. | The web service that Confluence should query. Available values:
|
(Unnamed in wiki markup) | Yes | Not specified. | User ID. Identifies the IM contact by their ID, account name or screen name. |
Example:
<ac:macro ac:name="im"> <ac:parameter ac:name="showid">false</ac:parameter> <ac:parameter ac:name="service">skype</ac:parameter> <ac:default-parameter>MySkypeName</ac:default-parameter> </ac:macro>
Include Page macro
Inserts the contents of the specified page into the current one.
Macro name: include
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
(Unnamed in wiki markup) | Yes | (None.) | The name of the page whose content should be included on the current page To includecontent from a page in another space, type the space key followed by a colon (:) and the page name, like this:
To include a blog post, specify the date as well as the title of the blog post. For example: You can include pages from personal spaces using ~username as the space key, where 'username' is the person's username. For example, |
Example:
<ac:macro ac:name="include"> <ac:default-parameter>DOC:My chocolate page</ac:default-parameter> </ac:macro>
Info macro
Displays a block of text in a blue highlight box.
Macro name: info
Macro body: Accepts rich text.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
icon | No | true | Determines whether to display the ![]() |
title | No | (None) | The title of the information box. If specified, the title text will be displayed in bold next to the icon. |
Example:
The following example shows all parameters and a body:
<ac:macro ac:name="info"> <ac:parameter ac:name="icon">false</ac:parameter> <ac:parameter ac:name="title">This is my title</ac:parameter> <ac:rich-text-body> <p> <span>This is </span> <em>important</em> <span> information.</span> </p> </ac:rich-text-body> </ac:macro>
Below are some examples of the Info macro with various optional parameters used.
Description | Markup | What you will get |
---|---|---|
Info macro with a body defined and no optional parameters | <ac:macro ac:name="info"> <ac:rich-text-body><p>This is <em>important</em> information.</p></ac:rich-text-body></ac:macro> | |
Info macro with with a body and an optional Title parameter defined | <ac:macro ac:name="info"> <ac:parameter ac:name="title">This is my title</ac:parameter> <ac:rich-text-body><p>This is <em>important</em> information.</p></ac:rich-text-body> </ac:macro> | |
Info macro with a body and optional Title and Icon parameters defined | <ac:macro ac:name="info"> <ac:parameter ac:name="icon">false</ac:parameter> <ac:parameter ac:name="title">This is my title</ac:parameter> <ac:rich-text-body> <p> <span>This is </span> <em>important</em> <span> information.</span> </p> </ac:rich-text-body> </ac:macro> |
JIRA Issues macro
Displays one or more JIRA issues, and offers the option to create an issue in JIRA.
Macro name: jiraissues
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
| No |
| If this parameter is set to 'true', JIRA will return only the issues which allow unrestricted viewing. That is, the issues which are visible to anonymous viewers, as determined by JIRA's viewing restrictions. If this parameter is omitted or set to 'false', then the results depend on how your administrator has configured the communication between JIRA and Confluence. By default, Confluence will show only the JIRA issues which the user is authorised to view. Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The graphic user interface (macro browser) for the JIRA Issues macro does not offer this parameter. |
| No | The value of the 'url' parameter | If you specify a 'baseurl', then the link in the header, pointing to your JIRA site, will use this base URL instead of the value of the 'url' parameter. This is useful when Confluence connects to JIRA with a different URL from the one used by other users. |
| No | By default, the following columns are shown:
| A list of JIRA column names, separated by semi-colons (;). You can include any columns recognised by your JIRA site, including custom columns. See the JIRA documentation for a list of names. |
| No |
| If this parameter is set to 'true', the issue list will show the number of issues in JIRA. The count will be linked to your JIRA site. |
| No |
| The macro maintains a cache of the issues which result from the JIRA query. If the 'cache' parameter is set to 'off', the relevant part of the cache is cleared each time the macro is reloaded. (The value 'false' also works and has the same effect as 'off'.) Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The graphic user interface (macro browser) for the JIRA Issues macro does not offer this parameter. |
| No |
| The height in pixels of the table displaying the JIRA issues.
Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The graphic user interface (macro browser) for the JIRA Issues macro does not offer this parameter. |
| No |
| If the value is 'dynamic', the JIRA Issues macro offers an interactive display which people can manipulate as follows:
A value of 'static' will disable the dynamic display features. Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The graphic user interface (macro browser) for the JIRA Issues macro does not offer this parameter. |
| No | JIRA Issues | You can customise the title text at the top of the JIRA issues table with this parameter. For instance, setting the title to 'Bugs-to-fix' will replace the default 'JIRA Issues' text. This can help provide more context to the list of issues displayed. Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The graphic user interface (macro browser) for the JIRA Issues macro does not offer this parameter. |
| Yes | none | The URL of the XML view of your selected issues in JIRA Issue Navigator. Note: If the URL in the 'url' parameter does not contain a |
| No | 100% | The width of the table displaying the JIRA issues. Can be indicated either as a percentage (%) or in pixels (px). Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The graphic user interface (macro browser) for the JIRA Issues macro does not offer this parameter. |
Example:
Example using a URL that points to the XML view of a JIRA search:
<ac:macro ac:name="jiraissues"> <ac:parameter ac:name="anonymous">true</ac:parameter> <ac:parameter ac:name="columns">type;key;summary</ac:parameter> <ac:parameter ac:name="url">http://jira.atlassian.com/sr/jira.issueviews:searchrequest-xml/temp/SearchRequest.xml?jqlQuery=project+%3D+CONF+AND+%28summary+%7E+jiraissues+OR+description+%7E+jiraissues+OR+comment+%7E+jiraissues%29&tempMax=10</ac:parameter> </ac:macro>
Example using JQL – note that Confluence will insert the server
and serverId
parameters, based on settings in Application Links:
<ac:macro ac:name="jira"> <ac:parameter ac:name="columns">key,summary,type,created,assignee,status</ac:parameter> <ac:parameter ac:name="server">Atlassian JIRA</ac:parameter> <ac:parameter ac:name="serverId">144880e9-a1111-333f-9412-ed999a9999fa</ac:parameter> <ac:parameter ac:name="jqlQuery">project = CONF AND component = documentation AND resolution = unresolved</ac:parameter> </ac:macro>
JUnit Report macro
Display a summary of JUnit test results.
Macro name: junitreport
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
| Must include either the directory or the url parameter | (None) | URL of a directory containing your test result files. This must be a directory name and not the XML file itself. Overrides the Note: When using a local drive, you must use a directory name and not the XML file itself. |
| No |
| Level of detail required in the report. Available values:
|
| Must include either the directory or the url parameter | (None) | URL of a particular test result XML file. This parameter is overridden by the For Confluence installations that require authentication, you can specify login credentials as part of this parameter, in the form of URL parameters:
|
| No |
| If the value of this parameter is |
Example:
<ac:macro ac:name="junitreport"> <ac:parameter ac:name="reportdetail">summary</ac:parameter> <ac:parameter ac:name="directory">http://confluence.com/download/attachments/123/</ac:parameter> <ac:parameter ac:name="debug">true</ac:parameter> <ac:parameter ac:name="url">http://confluence.com/download/attachments/123/file.xml</ac:parameter> </ac:macro>
Labels List macro
Displays a hyperlinked alphabetical index of all labels within the current space.
Macro name: listlabels
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
| No | Current space | The key of the space whose labels you want to display. |
Example:
<ac:macro ac:name="listlabels"> <ac:parameter ac:name="spaceKey">DOC</ac:parameter> </ac:macro>
Livesearch macro
Add a dynamic search box to a wiki page.
Macro name: livesearch
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
| No | (None) | Uniquely identifies the Livesearch macro when there are more than one Livesearch macros in a page. |
| No | All spaces | Specify a space key to limit the search to the given space. |
Example:
<ac:macro ac:name="livesearch"> <ac:parameter ac:name="id">mysearch1</ac:parameter> <ac:parameter ac:name="spaceKey">DOC</ac:parameter> </ac:macro>
Loremipsum macro
Display a few paragraphs of pseudo-Latin text.
Macro name: loremipsum
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
(No name in wiki markup) | No | 3 | Number of paragraphs. Determines the amount of pseudo-Latin (space-filler) text to display. The macro will display a maximum number of 30 paragraphs. |
Example:
<ac:macro ac:name="loremipsum"> <ac:default-parameter>2</ac:default-parameter> </ac:macro>
Multimedia macro
Displays videos, animations and more, sourced from a file attached to a Confluence page and displayed on your page.
Macro name: multimedia
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
| No | Current page | Name of the page to which the multimedia file is attached. |
| No | Current space | Space key of the page that has the multimedia file attached. |
| Yes | None | File name of the multimedia file, which is attached to a Confluence page. |
| No | If not specified, the browser will determine the width based on the file type. | Width of the movie window to be displayed on the page. By default, this value is specified in pixels. You can also choose to specify a percentage of the window's width, or any other value accepted by HTML. |
| No | If not specified, the browser will determine the height based on the file type. | Height of the movie window to be displayed on the page. By default, this value is specified in pixels. You can also choose to specify a percentage of the window's height, or any other value accepted by HTML. |
| No |
| If the parameter is set to |
Example:
<ac:macro ac:name="multimedia"> <ac:parameter ac:name="page">Macros</ac:parameter> <ac:parameter ac:name="name">ninjas.swf</ac:parameter> <ac:parameter ac:name="space">DOC</ac:parameter> <ac:parameter ac:name="autostart">true</ac:parameter> </ac:macro>
Navigation Map macro
Displays a navigable map of the pages tagged with a given label.
Macro name: navmap
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
(Unnamed in wiki markup) | Yes | (None) | The label that pages must contain to be included in the navigation map. |
| No |
| The number of cells in a row. |
| No | (None) | A title for the navigation map. |
| No |
| Height of the cells, in pixels. |
| No |
| Width of the cells, in pixels. |
| No | (None) | Not applicable to Confluence OnDemand. The name of a Velocity template that defines a theme for the navigation map. The name of your theme file must have the following format: Put your theme file in the |
Example:
<ac:macro ac:name="navmap"> <ac:parameter ac:name="wrapAfter">4</ac:parameter> <ac:parameter ac:name="title">My map name</ac:parameter> <ac:parameter ac:name="cellHeight">50px</ac:parameter> <ac:parameter ac:name="theme">navmap-mytheme.vm</ac:parameter> <ac:parameter ac:name="cellWidth">80px</ac:parameter> <ac:default-parameter>mylabel</ac:default-parameter> </ac:macro>
Network macro
Displays a list of Network activity for users on your Confluence site.
Macro name: network
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
(Unnamed in wiki markup) | Yes | following | The display mode, which determines the set of users to be listed, based on their relationship to the specified user:
|
| No | Current user's username | The username of the Confluence user whose network interactions you wish to show. |
| No |
| The maximum number of users to show. If the number of users exceeds the specified maximum, then the macro provides a 'Show All' link. This link leads to the specified user's network view, showing the complete list of network interactions. |
| No |
| Determines how the user's network is displayed:
|
Example:
<ac:macro ac:name="network"> <ac:parameter ac:name="username">admin</ac:parameter> <ac:parameter ac:name="max">10</ac:parameter> <ac:parameter ac:name="theme">full</ac:parameter> <ac:default-parameter>followers</ac:default-parameter> </ac:macro>
Noformat macro
Displays a block of text in monospace font.
Macro name: noformat
Macro body: Accepts plain text.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
nopanel | No | false | Determines whether the macro draws a box around the content. Available values:
|
Example:
<ac:macro ac:name="noformat"> <ac:parameter ac:name="nopanel">true</ac:parameter> <ac:plain-text-body><![CDATA[http://www.example.com]]></ac:plain-text-body> </ac:macro>
Note macro
Displays a block of text in a yellow highlighted box.
Macro name: note
Macro body: Accepts rich text.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
title | No | (None) | The words that will appear in the header of the note block. |
icon | No | true | Determines whether an icon appears next to the title. The icon is an exclamation mark inside a yellow triangle. Available values:
|
Example:
<ac:macro ac:name="note"> <ac:parameter ac:name="icon">false</ac:parameter> <ac:parameter ac:name="title">My title</ac:parameter> <ac:rich-text-body> <p>This is the content of my note.</p> </ac:rich-text-body> </ac:macro>
Office Excel macro
Displays the content of an Excel spreadsheet on a wiki page.
Macro name: viewxls
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
name | Yes | (None.) | The file name of the Excel spreadsheet to be displayed. The document must be attached to a page on your Confluence site. |
page | No | The page containing the macro | The name of a Confluence page to which the Excel spreadsheet is attached. |
col | No | Last column with content | The number of the last column you want displayed, starting from '0' as the first column. Hint for reducing the size of the spreadsheet: Use the |
row | No | Last row with content | The number of the last row you want displayed, starting from '0' as the first row. |
grid | No | true | Determines whether the macro will show borders around the cells in the spreadsheet. Accepted values:
|
sheet | No | The most-recently viewed worksheet | The name of the worksheet that you want displayed. |
Example:
<ac:macro ac:name="viewxls"> <ac:parameter ac:name="col">5</ac:parameter> <ac:parameter ac:name="page">Docs</ac:parameter> <ac:parameter ac:name="name">My document.xls</ac:parameter> <ac:parameter ac:name="grid">false</ac:parameter> <ac:parameter ac:name="sheet">mysheet</ac:parameter> <ac:parameter ac:name="row">5</ac:parameter> </ac:macro>
Office PowerPoint macro
Displays the content of a PowerPoint presentation on a wiki page.
Macro name: viewppt
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
name | Yes | (None.) | The file name of the PowerPoint presentation to be displayed. The document must be attached to a page on your Confluence site. |
page | No | The page containing the macro | The name of a Confluence page to which the PowerPoint presentation is attached. |
height | No | The height of the macro display, specified in pixels (for example: 10px , or just 10 ) or as a percentage (for example: 20% ) of the window's height. | |
width | No | The width of the macro display, specified in pixels (for example: 10px , or just 10 ) or as a percentage (for example: 20% ) of the window's height. | |
slide | No | All slides, starting with the first, as a slide show | The number of the slide that you want displayed on the Confluence page, where the first slide is numbered zero. Instead of a slide show, the page will display just the single slide, represented as a JPEG image. |
Example:
<ac:macro ac:name="viewppt"> <ac:parameter ac:name="height">20%</ac:parameter> <ac:parameter ac:name="page">Docs</ac:parameter> <ac:parameter ac:name="width">20%</ac:parameter> <ac:parameter ac:name="name">My document.ppt</ac:parameter> <ac:parameter ac:name="slide">4</ac:parameter> </ac:macro>
Office Word macro
Displays the content of a Word document on a wiki page.
Macro name: viewdoc
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
name | Yes | (None.) | The file name of the Word document to be displayed. The document must be attached to a page on your Confluence site. |
page | No | The page containing the macro | The name of a Confluence page to which the Word document is attached. |
Example:
<ac:macro ac:name="viewdoc"> <ac:parameter ac:name="page">Docs</ac:parameter> <ac:parameter ac:name="name">My document.doc</ac:parameter> </ac:macro>
Page Index macro
Creates a hyperlinked alphabetical index of all page titles within the current space.
Macro name: index
Macro body: None.
Parameters: None.
Example:
<ac:macro ac:name="index"/>
Page Properties macro
Allows you to embed metadata into a page and then display that data in tabular form using the Page Properties Report macro .Previously known as the Metadata Details macro.
Macro name: details
Macro body: Accepts rich text.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
hidden | No | false | Determines whether the data in the Page Properties macro will be displayed on the current page. This setting does not affect the display of the detail in the Page Properties Report macro. |
label | No | (None) | The label used to identify the metadata on this page. Confluence will add this label to the page. |
Example:
<ac:macro ac:name="details"> <ac:parameter ac:name="hidden">true</ac:parameter> <ac:parameter ac:name="label">status</ac:parameter> <ac:rich-text-body> <table> <tbody> <tr> <td style="text-align: left;">Project Status</td> <td style="text-align: left;">Complete</td> </tr> <tr> <td colspan="1" style="text-align: left;">Team</td> <td colspan="1" style="text-align: left;">Green Parrots</td> </tr> <tr> <td colspan="1" style="text-align: left;">Deadline</td> <td colspan="1" style="text-align: left;">2012-09</td> </tr> </tbody> </table> </ac:rich-text-body> </ac:macro>
Page Properties Report macro
Presents a tabulated summary of selected metadata, which has been embedded on pages using the Page Properties macro. Previously known as the Details Summary macro.
Macro name: detailssummary
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
label | No | (None) | Identifies the metadata to be included in the Page Properties Report. The report will show data from the Page Properties macros on the pages in the current space that have this label on the page. |
Example:
<ac:macro ac:name="detailssummary"> <ac:parameter ac:name="label">status</ac:parameter> </ac:macro>
Page Tree macro
Displays a dynamic, hierarchical list of pages starting from a specified parent (root) page.
Macro name: pagetree
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
excerpt | No | false | Determines whether the page tree will show excerpts from each page. The excerpts must be defined on the individual pages by the Excerpt macro. Available values:
|
expandCollapseAll | No | false | Determines whether the macro will offer the 'expand all' and 'collapse all' options at the top of the page tree. Your readers can click these links to open or close all branches of the tree at once. Available values:
|
reverse | No | false | Used in combination with the Available values:
|
root | No | The home page of the space | Specifies the parent page for the page tree. The tree will include all children of the given page, plus their children and grand-children, and so on. The tree will not include the root page itself.
|
searchBox | No | false | Determines whether the macro will offer a search box above the page tree. The search box allows your readers to enter a search term, and then searches within the page tree for the specified value. Available values:
|
sort | No | position | Determines the order in which pages are displayed in the tree. This sort order is for display purposes only. It does not permanently re-arrange the page order. Available values:
|
startDepth | No | 1 | Indicates how many levels of children the tree should show when it opens for the first time. Available values: Any number greater than 0. |
Example:
<ac:macro ac:name="pagetree"> <ac:parameter ac:name="reverse">false</ac:parameter> <ac:parameter ac:name="sort">natural</ac:parameter> <ac:parameter ac:name="root">Page Name</ac:parameter> <ac:parameter ac:name="startDepth">3</ac:parameter> <ac:parameter ac:name="excerpt">true</ac:parameter> <ac:parameter ac:name="searchBox">true</ac:parameter> <ac:parameter ac:name="expandCollapseAll">true</ac:parameter> </ac:macro>
Page Tree Search macro
Adds a search box to your Confluence page and searches a hierarchy of pages starting from a specified parent (root) page.
Macro name: pagetreesearch
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
root | No | The home page of the space | Specifies the parent page for the page tree. The tree will include all children of the given page, plus their children and grand-children, and so on. The tree will not include the root page itself. |
Example:
<ac:macro ac:name="pagetreesearch"> <ac:parameter ac:name="root">My page name</ac:parameter> </ac:macro>
Panel macro
Displays a block of text within a customisable panel.
Macro name: panel
Macro body: Accepts rich text.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
title | No | (None) | The words that will appear in the header of the panel. |
borderStyle | No | solid | The style of the panel's border. Accepted values:
|
borderColor | No | The colour of the panel's border. Colours can be specified as HTML colour names or hexadecimal codes. | |
borderWidth | No | The width of the panel's border, in pixels. | |
bgColor | No | The background colour of the panel. Colours can be specified as HTML colour names or hexidecimal codes. | |
titleBGColor | No | The background colour of the title row of the panel. Colours can be specified as HTML colour names or hexadecimal codes. | |
titleColor | No | The colour of the text in the title row of the panel. Colours can be specified as HTML colour names or hexadecimal codes. |
Example:
<ac:macro ac:name="panel"> <ac:parameter ac:name="bgColor">#72bc72</ac:parameter> <ac:parameter ac:name="titleBGColor">#00a400</ac:parameter> <ac:parameter ac:name="title">My title</ac:parameter> <ac:parameter ac:name="borderStyle">dashed</ac:parameter> <ac:parameter ac:name="borderColor">blue</ac:parameter> <ac:parameter ac:name="titleColor">white</ac:parameter> <ac:rich-text-body> <p>A formatted panel</p> </ac:rich-text-body> </ac:macro>
PDF macro
Displays the content of a PDF document on a wiki page.
Macro name: viewpdf
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
name | Yes | (None.) | The file name of the PDF document to be displayed. The document must be attached to a page on your Confluence site. |
page | No | The page containing the macro | The name of a Confluence page to which the PDF document is attached. |
Example:
<ac:macro ac:name="viewpdf"> <ac:parameter ac:name="page">Docs</ac:parameter> <ac:parameter ac:name="name">My document.pdf</ac:parameter> </ac:macro>
Popular Labels macro
Displays the most popular labels used throughout your Confluence site or within a space.
Macro name: popular-labels
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
style | No | list | Determines how the macro displays the labels. Accepted values:
|
count | No | 100 | The number of labels to display. |
spaceKey | No | No restriction – include labels from all spaces in the site | If a space key is given, the macro will include only labels in that space. |
Example:
<ac:macro ac:name="popular-labels"> <ac:parameter ac:name="style">heatmap</ac:parameter> <ac:parameter ac:name="count">20</ac:parameter> <ac:parameter ac:name="spaceKey">ds</ac:parameter> </ac:macro>
Profile Picture macro
Displays a user's profile picture on a page.
Macro name: profile-picture
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
User | Yes | (None) | The username of a Confluence user. |
Example:
<ac:macro ac:name="profile-picture"> <ac:parameter ac:name="User">admin</ac:parameter> </ac:macro>
Recently Updated Dashboard macro
Displays a list of the most recently changed content within Confluence and is intended for use on the Confluence dashboard.
Macro name: recently-updated-dashboard
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
spaces | No | The space that contains the page on which the macro is added. | Filters content by space. The macro will display only the pages and other content which belong to the space(s) you specify here. Accepted values:
|
users | No | All users. | Filters by username of the user who updated the content. The macro will only display content created and updated by the user(s) you specify here. You can specify one or more usernames separated by commas. |
width | No | 100% | The width of the macro display, specified as a percentage of the window width. |
showProfilePic | No | false | Determines whether the macro displays profile pictures of the users who updated the content. Accepted values:
|
labels | No | None. Labels are not used to filter the content. | Filters content by label. The macro will display only the pages and other content which are tagged with the label(s) you specify here. You can specify one or more labels, separated by commas. Note: If there are no pages matching any of the specified labels, then Confluence will ignore the labels and will list all recently updated pages, as well as showing a message, "These labels don't exist and were ignored: xxx ". |
types | No | All content types. | Filters content by type. You can specify one or more types, separated by commas. Accepted values:
|
Example:
<ac:macro ac:name="recently-updated-dashboard"> <ac:parameter ac:name="spaces">ds</ac:parameter> <ac:parameter ac:name="users">admin</ac:parameter> <ac:parameter ac:name="width">50%</ac:parameter> <ac:parameter ac:name="showProfilePic">true</ac:parameter> <ac:parameter ac:name="labels">choc</ac:parameter> <ac:parameter ac:name="types">page</ac:parameter> </ac:macro>
Recently Updated macro
Displays a list of recently changed content (pages, news items, comments, etc).
Macro name: recently-updated
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
spaces | No | The space that contains the page on which the macro is added. | Filters content by space. The macro will display only the pages and other content which belong to the space(s) you specify here. You can specify one or more space keys, separated by a comma or a space.
Special values:
When specifying a personal space, remember to use the tilde (~) sign in front of the username, such as |
author | No | All users. | Filters by the username of the user who updated the content. The macro will only display content created and updated by the user(s) you specify here. You can specify one or more authors, separated by a comma or a space.For example:jsmith,jbrown To include content from one user, but exclude from another user: |
max | No | 15 | The maximum number of results to be displayed. The theoretical maximum value that this parameter can accept is 2 to the power of 31, minus 1 (or 2147483647). But this maximum is limited to 200 in the code, for performance reasons. More details are in this issue: CONF-19096 |
hideHeading | No | false | Determines whether the macro hides or displays the text 'Recently Updated' as a title above the list of content. Accepted values:
|
width | No | 100% | The width of the macro display, specified as a percentage of the window width. |
theme | No | concise | Choose the appearance of the macro. Accepted values:
|
showProfilePic | No | false | Determines whether the macro displays profile pictures of the users who updated the content. Accepted values:
|
labels | No | None. Labels are not used to filter the content. | Filters content by label. The macro will display only the pages and other content which are tagged with the label(s) you specify here. You can specify one or more labels, separated by commas. Note: If there are no pages matching any of the specified labels, then Confluence will ignore the labels and will list all recently updated pages, as well as showing a message, "These labels don't exist and were ignored: xxx ". Filter the results by label. The macro will display only the pages etc which are tagged with the label(s) you specify here.
|
types | No | All content types. | Filters content by type. You can specify one or more types, separated by commas. You can specify one or more types, separated by a comma or a space.To exclude content of a given content type, put a minus sign (-) immediately in front of that content type. For example: If you specify a content type of Available values:
|
Example:
<ac:macro ac:name="recently-updated"> <ac:parameter ac:name="spaces">ds</ac:parameter> <ac:parameter ac:name="author">admin</ac:parameter> <ac:parameter ac:name="max">10</ac:parameter> <ac:parameter ac:name="hideHeading">true</ac:parameter> <ac:parameter ac:name="width">50%</ac:parameter> <ac:parameter ac:name="theme">sidebar</ac:parameter> <ac:parameter ac:name="showProfilePic">true</ac:parameter> <ac:parameter ac:name="labels">choc</ac:parameter> <ac:parameter ac:name="types">page</ac:parameter> </ac:macro>
Recently Used Labels macro
Lists labels most recently used in a specified scope (global, space, or personal)
Macro name: recently-used-labels
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
title | No | None. | Adds a title to the top of the list in table style. Titles are only visible when the style parameter is set to table. |
scope | No | global | The scope of labels to be displayed in the list. Accepted values:
|
style | No | list | The style of the list of labels:
|
count | No | 10 | The maximum number of labels to display in the list. |
Example:
<ac:macro ac:name="recently-used-labels"> <ac:parameter ac:name="title">My title</ac:parameter> <ac:parameter ac:name="scope">space</ac:parameter> <ac:parameter ac:name="style">table</ac:parameter> <ac:parameter ac:name="count">20</ac:parameter> </ac:macro>
Related Labels macro
Lists labels frequently appearing on the same pages as the current page's labels.
Macro name: related-labels
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
labels | No | None | The label(s) for which you want to view related labels. If you include more than one label, separate them with commas. |
Example:
<ac:macro ac:name="related-labels"> <ac:parameter ac:name="labels">choc,cake</ac:parameter> </ac:macro>
RSS Feed macro
Displays the contents of an RSS feed.
Macro name: rss
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
max | No | 15 | The maximum number of news items to display. |
showTitlesOnly | No | false | Determines whether the macro will show only the titles of the news items, or the titles plus content. Accepted values:
|
url | Yes | (None) | The URL of the RSS feed. |
titleBar | No | true | Determines whether the macro will show a title above the list of news items. Accepted values:
|
Example:
<ac:macro ac:name="rss"> <ac:parameter ac:name="max">10</ac:parameter> <ac:parameter ac:name="showTitlesOnly">true</ac:parameter> <ac:parameter ac:name="url">http://myblog.com/feed</ac:parameter> <ac:parameter ac:name="titleBar">false</ac:parameter> </ac:macro>
Search Results macro
Searches Confluence, and includes the results in the page.
Macro name: search
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
lastModified | No | (None.) | Defines a period of time in weeks, days, hours and/or minutes. The macro will display the content modified within that time frame. These are the values you can use:
For example:
Notes:
|
query | Yes | (None.) | The search terms which this macro will use to generate its results. You can refine your search query by using operators such as 'AND' and 'OR'. For example: For more information, take a look at the documentation on the Confluence search syntax. |
contributor | No | (None.) | The username of a Confluence user. If this parameter is present, the macro will show only content created or updated by the given user. |
maxLimit | No | 10 | The maximum number of search results to display. |
type | No | (None.) | The type of content to include in the search results. Accepted values:
|
Example:
<ac:macro ac:name="search"> <ac:parameter ac:name="lastModified">3w</ac:parameter> <ac:parameter ac:name="query">choc</ac:parameter> <ac:parameter ac:name="contributor">admin</ac:parameter> <ac:parameter ac:name="maxLimit">10</ac:parameter> <ac:parameter ac:name="type">page</ac:parameter> <ac:parameter ac:name="spacekey">ds</ac:parameter> </ac:macro>
Section macro
Used with the Column macro to define columns on a page. See Working with page layouts and columns and sections.
Macro name: section
Macro body: Rich text, consisting of one or more Column macros.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
| No | False | If the value is true , the columns in this section will have a dashed border. |
Example:
<ac:macro ac:name="section"> <ac:parameter ac:name="border">true</ac:parameter> <ac:rich-text-body> <ac:macro ac:name="column"> <ac:parameter ac:name="width">100px</ac:parameter> <ac:rich-text-body> <p>This is the content of <strong>column 1</strong>.</p> </ac:rich-text-body> </ac:macro> <ac:macro ac:name="column"> <ac:rich-text-body> <p>This is the content of <strong>column 2</strong>.</p> </ac:rich-text-body> </ac:macro> </ac:rich-text-body> </ac:macro>
Space Attachments macro
Displays a list of attachments belonging to the current space.
Macro name: space-attachments
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
showFilter | No | true | Determines whether or not the filter panel is shown. If you select this option, people viewing the page will be able to filter the list of attachments by file type (extension) and by label. Accepted values:
|
space | No | Current space. | Determines the Confluence space containing the attachments that the macro will display. |
Example:
<ac:macro ac:name="space-attachments"> <ac:parameter ac:name="showFilter">false</ac:parameter> <ac:parameter ac:name="space">ds</ac:parameter> </ac:macro>
Space Details macro
Displays the details of a Confluence space, including the space name, description, and more.
Macro name: space-details
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
width | No | 100% | The width of the space details table, specified as a percentage of the page width. |
Example:
<ac:macro ac:name="space-details"> <ac:parameter ac:name="width">50%</ac:parameter> </ac:macro>
Space Jump macro
Allows you to link from a page in one space to a page with the same name in another space, without knowing the name of the page when you create the link.
Macro name: spacejump
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
alias | No | The name of the current page | The text to display as the hyperlinked text. |
space | Yes | (None.) | The key of the space that contains a page with the same name as the current page. Space keys are case sensitive. |
Example:
<ac:macro ac:name="spacejump"> <ac:parameter ac:name="alias">my link</ac:parameter> <ac:parameter ac:name="space">ds</ac:parameter> </ac:macro>
Spaces List macro
Displays a list of the spaces visible to the user.
Macro name: spaces
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
(Unnamed in wiki markup) | No | All spaces | Specify the view from which spaces are listed. Accepted values:
|
width | No | 100% | The width of the list of spaces, specified as a percentage (%) of the window. |
Example:
<ac:macro ac:name="spaces"> <ac:parameter ac:name="width">80%</ac:parameter> <ac:default-parameter>favourite</ac:default-parameter> </ac:macro>
Status macro
Displays a coloured lozenge, useful for reporting project status.
Macro name: status
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
colour | No | Grey | The colour of the lozenge. Accepted values: |
title | No | The value of the colour parameter | The text that will appear inside the lozenge. If you do not specify any text, the title will be the colour of the lozenge, that is 'Grey', 'Red', 'Yellow', 'Green' or 'Blue'. |
subtle | No | false | The style of the lozenge and its border. Accepted values:
|
Example:
<ac:macro ac:name="status"> <ac:parameter ac:name="colour">Green</ac:parameter> <ac:parameter ac:name="title">On track</ac:parameter> <ac:parameter ac:name="subtle">true</ac:parameter> </ac:macro>
Table of Contents macro
Displays a table of contents based on the headings on the page.
Macro name: toc
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
printable | No | true | If you set this parameter to false , the table of contents will not be visible when you print the page. |
style | No | none | The style of bullet point for each list item. You can use any valid CSS style. For example:
|
maxLevel | No | 7 | Maximum heading level. Use this parameter to select the highest heading level to include. For example, a value of 2 will list h1 and h2 levels, but will not include h3 and below. |
indent | No | (None) | This parameter applies to vertical lists only ( Use this parameter to indent the list items according to CSS quantities. For example, a value of |
minLevel | No | 1 | Minimum heading level. The heading level at which the table of contents will start. For example, a value of 2 will list h2, h3, and h4 headings, but will not include h1 headings. |
class | No | (None) | A CSS class name. If you have a custom style sheet, you can use this parameter to output the table of contents with the specified class attribute. |
exclude | No | (None) | Specifies the headings to exclude by pattern matching. The value must be a regular expression. If this parameter is specified, the table of contents will include only the headings that match the regular expression. Example: |
type | No | list | Defines the overall format of the table of contents. Available values:
|
outline | No | false | A value of true will apply outline numbering to the headings as displayed in the table of contents. For example: 1.1, 1.2, 1.3. |
separator | No | brackets | This parameter applies to flat lists only ( Available values:
|
include | No | (None) | Specifies the headings to include by pattern matching. The value must be a regular expression. If this parameter is specified, the table of contents will ignore any headings that do not match the regular expression. Example: See Sun's Regex documentation for examples of constructing regular expression strings. |
Example:
This example shows a list-type table of contents.
<ac:macro ac:name="toc"> <ac:parameter ac:name="printable">true</ac:parameter> <ac:parameter ac:name="style">square</ac:parameter> <ac:parameter ac:name="maxLevel">2</ac:parameter> <ac:parameter ac:name="indent">5px</ac:parameter> <ac:parameter ac:name="minLevel">2</ac:parameter> <ac:parameter ac:name="class">bigpink</ac:parameter> <ac:parameter ac:name="exclude">[1//2]</ac:parameter> <ac:parameter ac:name="type">list</ac:parameter> <ac:parameter ac:name="outline">true</ac:parameter> <ac:parameter ac:name="include">.*</ac:parameter> </ac:macro>
This example shows a flat table of contents.
<ac:macro ac:name="toc"> <ac:parameter ac:name="printable">true</ac:parameter> <ac:parameter ac:name="maxLevel">2</ac:parameter> <ac:parameter ac:name="minLevel">2</ac:parameter> <ac:parameter ac:name="class">bigpink</ac:parameter> <ac:parameter ac:name="exclude">[1//2]</ac:parameter> <ac:parameter ac:name="type">flat</ac:parameter> <ac:parameter ac:name="outline">true</ac:parameter> <ac:parameter ac:name="separator">pipe</ac:parameter> <ac:parameter ac:name="include">.*</ac:parameter> </ac:macro>
Table of Content Zone macro
Displays a table of contents from a defined page 'zone'.
Macro name: toc-zone
Macro body: Accepts rich text.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
location | Yes | both | Determines where the macro will display the table of contents, relative to the zone delineated by the macro. Accepted values:
|
printable | No | true | If you set this parameter to false , the table of contents will not be visible when you print the page. |
style | No | none | The style of bullet point for each list item. You can use any valid CSS style. For example:
|
maxLevel | No | 7 | Maximum heading level. Use this parameter to select the highest heading level to include. For example, a value of 2 will list h1 and h2 levels, but will not include h3 and below. |
indent | No | (None) | This parameter applies to vertical lists only ( Use this parameter to indent the list items according to CSS quantities. For example, a value of |
minLevel | No | 1 | Minimum heading level. The heading level at which the table of contents will start. For example, a value of 2 will list h2, h3, and h4 headings, but will not include h1 headings. |
class | No | (None) | A CSS class name. If you have a custom style sheet, you can use this parameter to output the table of contents with the specified class attribute. |
exclude | No | (None) | Specifies the headings to exclude by pattern matching. The value must be a regular expression. If this parameter is specified, the table of contents will include only the headings that match the regular expression. Example: |
type | No | list | Defines the overall format of the table of contents. Available values:
|
outline | No | false | A value of true will apply outline numbering to the headings as displayed in the table of contents. For example: 1.1, 1.2, 1.3. |
separator | No | brackets | This parameter applies to flat lists only ( Available values:
|
include | No | (None) | Specifies the headings to include by pattern matching. The value must be a regular expression. If this parameter is specified, the table of contents will ignore any headings that do not match the regular expression. Example: See Sun's Regex documentation for examples of constructing regular expression strings. |
Example:
<ac:macro ac:name="toc-zone"> <ac:parameter ac:name="printable">false</ac:parameter> <ac:parameter ac:name="maxLevel">2</ac:parameter> <ac:parameter ac:name="minLevel">2</ac:parameter> <ac:parameter ac:name="location">top</ac:parameter> <ac:parameter ac:name="type">flat</ac:parameter> <ac:parameter ac:name="outline">true</ac:parameter> <ac:parameter ac:name="separator">pipe</ac:parameter> <ac:rich-text-body> <p>Only headings within this block are included in the table of contents.</p> </ac:rich-text-body> </ac:macro>
Tasklist macro
Displays a dynamic task list which can be modified in view mode.
Macro name: tasklist
Macro body: Accepts wiki markup, for defining the tasks.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
| No | Task List | The title to be displayed above the list of tasks. |
enableLocking | No | false | Determines whether the macro allows users to lock individual tasks so that they cannot be changed. Accepted values:
|
width | No | 530px | The width of the task list, specified in pixels (for example: 200px ) or as a percentage of page width (for example: 20% ). |
promptOnDelete | No | false | Determines whether Confluence will ask the user to confirm the deletion of a task. Accepted values:
|
Example:
Note: The CDATA
content inside the macro body defines the tasks in the list. This content is coded in wiki markup, as a table.The first row in the table defines the column headings for the task list. Each subsequent row defines a task.
<ac:macro ac:name="tasklist"> <ac:parameter ac:name="title">My title</ac:parameter> <ac:parameter ac:name="enableLocking">true</ac:parameter> <ac:parameter ac:name="width">20%</ac:parameter> <ac:parameter ac:name="promptOnDelete">true</ac:parameter> <ac:plain-text-body><![CDATA[||Completed||Priority||Locked||CreatedDate||CompletedDate||Assignee||Name|| |F|M|F|1371784117215| |admin|Book tickets| |F|M|F|1371784127222| |admin|Check passport expiry| ]]></ac:plain-text-body> </ac:macro>
Tip macro
Displays a block of text in a green box.
Macro name: tip
Macro body: Accepts rich text.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
icon | No | true | Determines whether to display the standard Confluence tip icon in the title bar of the tip box. |
title | No | (None) | The title of the tip box. If specified, the title text will be displayed in bold next to the icon. |
Example:
<ac:macro ac:name="tip"> <ac:parameter ac:name="icon">false</ac:parameter> <ac:parameter ac:name="title">My title</ac:parameter> <ac:rich-text-body> <p>This is my hint.</p> </ac:rich-text-body> </ac:macro>
User List macro
Displays a list of Confluence users in a given group.
Macro name: userlister
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
groups | Yes | (None.) | One or more groups containing the Confluence users that the macro will list. Accepted values:
|
online | No | All users | Instructs the macro to differentiate between online and offline users. Accepted values:
Note: In order to make this parameter functional, a System Administrator needs to enable the User Log In Listener for your Confluence site. Not applicable to Confluence OnDemand. |
Example:
<ac:macro ac:name="userlister"> <ac:parameter ac:name="groups">confluence-users</ac:parameter> <ac:parameter ac:name="online">false</ac:parameter> </ac:macro>
User Profile macro
Displays a summary of a given Confluence user's profile.
Macro name: profile
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
user | Yes | (None.) | The username of the Confluence user whose profile summary you wish to show. |
Example:
<ac:macro ac:name="profile"> <ac:parameter ac:name="user">admin</ac:parameter> </ac:macro>
User Status List macro
Displays a history of a given Confluence user's status updates.
Macro name: status-list
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
username | Yes | (None.) | The username of the Confluence user whose status updates you wish to show. |
Example:
<ac:macro ac:name="status-list"> <ac:parameter ac:name="username">admin</ac:parameter> </ac:macro>
Warning macro
Displays a block of text in a red highlight box.
Macro name: warning
Macro body: Accepts rich text.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
icon | No | true | Determines whether to display a warning icon in the title bar of the text box. |
title | No | (None.) | The title of the warning box. If specified, the title text will be displayed in bold next to the icon. |
Example:
<ac:macro ac:name="warning"> <ac:parameter ac:name="icon">false</ac:parameter> <ac:parameter ac:name="title">This is my title</ac:parameter> <ac:rich-text-body> <p>This is <em>important</em> information.</p> </ac:rich-text-body> </ac:macro>
Widget Connector macro
Displays content from other websites including videos, slide shows, twitter chats, documents and more on your Confluence page.
Macro name: widget
Macro body: None.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
height | No | The height of the display, in pixels. Specify the number of pixels only. | |
width | No | The width of the display, in pixels. Specify the number of pixels only. | |
url | Yes | (None.) | The URL provided by the external website for embedding content from that website onto another web page. |
Example:
<ac:macro ac:name="widget"> <ac:parameter ac:name="height">400</ac:parameter> <ac:parameter ac:name="width">400</ac:parameter> <ac:parameter ac:name="url">http://www.google.com/ig/directory?synd=open&num=24&url=http://www.gadzi.com/gadgets/monkey.xml&output=html</ac:parameter> </ac:macro>
Macro format notes
Macro bodies
Some macros accept a body as well as parameters.
- The Info macro and Expand macro are examples of macros that accept a rich text body.
- The Code Block macro is a good example of a macro that accepts a plain text body.
Plain text bodies
The body of a plain text macro must be inside a CDATA
block. So the following is not sufficient:
<ac:plain-text-body>text</ac:plain-text-body>
The correct usage is:
<ac:plain-text-body><![CDATA[text]]></ac:plain-text-body>
Other notes
- The 'Required' column indicates whether the parameter is required on data entry. If the parameter is not supplied, Confluence will insert default values as indicated in the 'Default' column.
A request from the Atlassian technical writers about comments and feedback: When adding comments to this page, please restrict your comments to constructive feedback on the documentation itself: Things we've missed in the documentation, and things that will be useful to other readers. If you have other feedback about the editor, wiki markup, the XML storage format, and Confluence 4 in general, please add your comments in the section titled Confluence 4 Editor - Customer Feedback, and its child pages. Our reason for this request: When a page attracts a large number of comments, it makes it difficult for everyone to read the page, and to add or respond to comments about the documentation. Thanks.