Confluence Storage Format for Macros

Work in progress

We are adding the details for each macro in turn. They are not all here yet. See CONF-24972 - Getting issue details... STATUS .

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.

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

default-parameter

(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>

On this page:

Related pages:

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: `false` - Displays only the latest version of each attachment. `true` – Displays all versions of each attachment, including the old versions.
`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: To match a file suffix of 'jpg', use `.jpg` (not `.jpg`). To match file names ending in 'jpg' or 'png', use `.jpg`,`.png` Here is a tutorial on regular expressions.
`sortBy`	No	`date`	Available values: `date` `size` `name`
`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 `sortBy` type: Reverse chronological for 'date'. Largest to smallest for 'size'. Alphabetical for 'name'.	Available values: `ascending` `descending`
`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: `entire` – Display the whole content of each blog post. `excerpts` – Display a short extract from each blog post. If the post contains an Excerpt macro, the Blog Posts macro will display the content defined in the Excerpt macro. If the post does not contain an Excerpt macro, the Blog Posts macro will display the first few sentences of the post. `titles` – Display a list of blog posts, showing titles only.
`spaces`	No	`@self`	One or more space keys, separated by a comma or a space. To exclude content in a specific space, put a minus sign (-) immediately in front of that space key. For example: If you specify a space key of `-BADSPACE` you will get only content which is not in the BADSPACE. To indicate that the results must come from a specific space, put a plus sign (+) immediately in front of that space key. For example: If you specify a space key of `+GOODSPACE` you will get only content in GOODSPACE. (Note that this is not particularly useful, because each content item belongs to one space only. If you put a plus sign next to one space key and list other space keys too, the other space keys will be ignored.) Special values: `@self` — The current space. `@personal` — All personal spaces. `@global` — All site spaces. `@favorite` — The spaces you have marked as favourite. `@favourite` — The same as `@favorite` above. `@all` — All spaces in your Confluence site. `*` — The same as `@all` above. When specifying a personal space, remember to use the tilde (~) sign in front of the username, such as `~jbloggs` or `~jbloggs@example.com`.
`author`	No	(None)	One or more usernames, separated by commas.
`time`	No	(None)	Available values: `m` — Minutes `h` — Hours `d` — Days `w` — Weeks For example, `time=12h` – Display blog posts created in the last twelve hours. `time=7d` – Display blog posts created in the last seven days.
`reverse`	No	`false`	A value of `true` changes the sort order.
`sort`	No	`creation`	Available values: title — Sort alphabetically by title. creation — Sort by the date on which the content was added. modified — Sort by the date on which the content was last updated.
`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. To exclude content which matches a given label, put a minus sign (-) immediately in front of that label value. For example: If you specify a label value of `-badpage` you will get only content which is not labelled with 'badpage'. To indicate that the results must match a given label value, put a plus sign (+) immediately in front of that label value. For example: If you specify a label value of `+superpage,+goodpage` you will get only content which has at least two labels, being 'superpage' and 'goodpage'.

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 `timeSeries` parameter. Available values: Standard charts `- pie, bar, line, area` XY plots – `xyArea, xyBar, xyLine, xyStep, xyStepArea, scatter, timeSeries` Other charts – `gantt` (beta)
`orientation`	No	`vertical`	The display orientation. Applies to area, bar and line charts. Available values: `vertical` – y-axis is vertical `horizontal` – x-axis is vertical
`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	75 percent for 3D charts 50 percent for non-stacked area charts 100 percent for all other charts	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: false – the data is not displayed. `true` or `after` – the data is displayed after the chart. `before –` the data is displayed before the chart.
`imageFormat`	No	`png`	The image format to be used for the chart. Available values: `png` `jpg`

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: `vertical` – data table columns will be interpreted as series. `horizontal –` data tables rows will be interpreted as series.
`timeSeries`	No	`false`	If '`true`', the x values in an XY plot will be treated as time series data and so will be converted according date formats.
`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: `millisecond, second, minute, hour, day, week, month, quarter, year`
`language`	No	(None)	Use in combination with the `country` parameter to form a locale. These additional number and date formats will be used for data conversion before the default languages. 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: `true` — the macro tries to convert numeric and date values that do not totally match any of the default or user-specified formats. `false` — the macro enforces strict data formatting. If there are data format errors, the chart will not be produced.

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: `up45` — 45 degrees going upward `up90` — 90 degrees going upward `down45` — 45 degrees going downward `down90` — 90 degrees going downward
`dateTickMarkPosition`	No	`start`	Placement of the date tick mark. Available values: `start` — tick mark is at the start of the date period. `middle` — tick mark is in the middle of the date period. `end` — tick mark is at the end of the date period.

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:

%0% is replaced by the pie section key.
%1% is replaced by the pie section numeric value.
%2% is replaced by the pie section percent value.

Example 1: To display something like 'Independent = 20':

%0% = %1%

Example 2: To display something like 'Independent (20%)':

%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: `^attachmentName.png` — the chart is saved as an attachment to the current page. `page name^attachmentName.png` — the chart is saved as an attachment to the page name provided. `spacekey:page name^attachmentName.png` — the chart is saved as an attachment to the page name provided in the space indicated.
`attachmentVersion`	No	`new`	Defines the the versioning mechanism for saved charts. Available values: `new` — creates new version of the attachment. `replace` — replaces all previous versions of the chart. To replace an existing attachment, the user must be authorised to remove attachments for the page specified. `keep` — only saves a new attachment if an existing export of the same name does not exist. An existing attachment will not be changed or updated.
`attachmentComment`	No	(None)	Comment used for a saved chart attachment.
`thumbnail`	No	`false`	If `true`, the chart image attachment will be shown as a thumbnail (small, expandable) image.

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: `creation` – Sort by the date on which the page was created. `title` – Sort alphabetically by page name. `modified` – Sort by the date on which the page was last updated.
`style`	No	Bullet list	A heading style to be applied to the list of child pages. Available values: `h1` (heading level 1) through to `h6` (heading level 6).
`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: `MYSPACE:My page` If the value of this parameter is a forward slash (`/`) the macro will list the pages at the root of the current space. In other words, the pages without parents.
`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 `true`, Confluence will display all levels of child pages. This setting will override the `depth` setting.

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 `Confluence` (also known as `Default`), which is typically black and coloured text on a blank background. Available themes: `DJango` `Emacs` `FadeToGrey` `Midnight` `RDark` `Eclipse` `Confluence (same as default)`
`linenumbers`	No	`false`	If `true`, a line number will be shown to the left of each line of code. Numbering is incremented by 1. If `false`, no line numbers are shown.
`language`	No	`java`	Specifies the language (or environment) for syntax highlighting. (none) — that is, no syntax highlighting `actionscript3` `bash` `csharp` — that is, C# `coldfusion` `cpp` — that is, C++ `css` `delphi` `diff` `erlang` `groovy` `java` `javafx` `javascript` `perl` `php` `powershell` `python` `ruby` `scala` `sql` `vb` — that is, Visual Basic `html/xml`
`firstline`	No	`1`	When `linenumbers` is `true`, this value defines the number of the first line of code.
`collapse`	No	`false`	If `true`, the code macro's content will be collapsed upon visiting or refreshing the Confluence page. Clicking the 'expand source' link allows you to view the content. If `false`, the code macro's content is always displayed in full.

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
`width`	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. You can specify one or more space keys, separated by a comma or a space. To exclude content in a specific space, put a minus sign (-) immediately in front of that space key. For example: If you specify a space key of `-BADSPACE` you will get only content which is not in the BADSPACE. To indicate that the results must come from a specific space, put a plus sign (+) immediately in front of that space key. For example: If you specify a space key of `+GOODSPACE` you will get only content in GOODSPACE. (Note that this is not particularly useful, because each content item belongs to one space only. If you put a plus sign next to one space key and list other space keys too, the other space keys will be ignored.) Special values: `@self` — The current space. `@personal` — All personal spaces. `@global` — All site spaces. `@favorite` — The spaces you have marked as favourite. `@favourite` — The same as `@favorite` above. `@all` — All spaces in your Confluence site. `*` — The same as `@all` above. When specifying a personal space, remember to use the tilde (~) sign in front of the username, such as `~jbloggs` or `~jbloggs@example.com`.
`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. You can specify one or more authors, separated by a comma. For example: `jsmith,jbrown`
`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: title — Sort alphabetically by title. creation — Sort by the date on which the content was added. modified — Sort by the date on which the content was last updated.
`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. To exclude content which matches a given label, put a minus sign (-) immediately in front of that label value. For example: If you specify a label value of `-badpage` you will get only content which is not labelled with 'badpage'. To indicate that the results must match a given label value, put a plus sign (+) immediately in front of that label value. For example: If you specify a label value of `+superpage,+goodpage` you will get only content which has at least two labels, being 'superpage' and 'goodpage'.
`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 `-blogpost` you will get pages and all other content except for blog posts. Available values: `page` — ages. `blogpost` or `news` — blog posts, also known as news items. `attachment` – attachments.
`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

default-parameter

(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 specifed 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`.

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: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
`limit`	No	(None)	Limits the number of contributors displayed in the list.
`spaces`	No	Current space	Specifies the space key of the Confluence space to search. Space keys are case sensitive. Special values: `@global` — All site spaces. `@personal` — All personal spaces. `@all` — All spaces in the Confluence site. You can specify one or more space keys or special values, separated by commas. If no `page` and `labels` are specified, all pages from the specified set of spaces are included.
`reverse`	No	`false`	Reverses the order of contributors in the list. Must be used in conjunction with the `order` parameter.
scope	No	The specified page only	Specifies additional pages to include when generating the list of contributors. Available values: `children –` only the child pages of the specified page. `descendants –` all descendants of the specified page.
`labels`	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	`false`	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.
`showCount`	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: `pages –` pages `blogposts –` blog posts.
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: `authors` - includes people who created or have edited the page(s) `comments` - includes people who have added comments to the page(s) `labels` - includes people who have added labels to the page(s) `watches` - includes people who are watching the page(s). You can specify one or more contribution types, separated by commas.
mode	No	inline	Determines how the list of contributors is formatted: `inline` — a comma-separated list `list` — a bullet list.
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: `count` – sorts the names based on the total number of contributions to the page(s) `name` – sorts the names into alphabetical order `update` – sorts the names by the date of their last contribution to the page(s).
page	No	The current page	Specifies the page to use when generating the list of contributors. If `page` and `spaces` are left blank, the current page is assumed.
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
`limit`	No	(None)	Limits the number of contributors or pages displayed in the table.
`spaces`	No	Current space	Specifies the space key of the Confluence space to search. Space keys are case sensitive. Special values: `@global` — All site spaces. `@personal` — All personal spaces. `@all` — All spaces in the Confluence site. You can specify one or more space keys or special values, separated by commas. If no `page` and `labels` are specified, all pages from the specified set of spaces are included.
`reverse`	No	`false`	Reverses the order of items in the table. Must be used in conjunction with the `order` parameter.
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: `children –` only the child pages of the specified page. `descendants –` all descendants of the specified page.
order	No	edits	Sets the criterion used for sorting items in the table. Available values: `edits` `–` sorts items in the table based on the total number of edits made, either by a contributor or to a page. `name` `–` sorts items in the table in alphabetical order, either by contributor or page name. `editTime` `–` sorts items in the table based on when the contributor last edited a page (or a specified set of pages) or when the page was lasted edited. `update` `–` sorts items in the table based on when the contributor last made any contribution to a page (or a specified set of pages) or when the page last had any contribution made to it.
page	No	The current page	A page title. Specifies the page to use when generating the list of contributors. If `page` and `spaces` are left blank, the current page is assumed.
`labels`	No	(None)	Limits contribution-based statistics to the specified labels only. You can specify one or more labels, separated by commas.
columns	No	`edits,comments,labels`	Determines the columns that should appear in the table. The statistics or type of information presented depends on the `groupby` parameter. Available values: `edits` – the number of times each contributor has edited the page(s) or the number of edits made to each page. `edited` – a list of the pages edited by each contributor or a list of contributors who have edited each page. `comments` – the number of times each contributor has added comments to the page(s) or the number of comments on each page. `commented` – a list of pages to which each contributor has added comments or a list of contributors who have commented on each page. `labels` – the number of times each contributor has added labels to the page(s) or the number of labels on each page. `labeled` – a list of pages to which each contributor has added labels or a list of contributors who have added a label to each page. `labellist` – a list of labels either added by each contributor or on each page. `watches` – the number of pages being watched by each contributor/person or the number of contributors/people watching each page. `watching` – a list of pages being watched by each contributor/person or a list of contributors/people watching each page. `lastupdate` – the last time each contributor made an update or when each page was last updated. Valid updates can include edits, comments or label modifications to a page. You can specify one or more columns, separated by commas.
groupby	No	`contributors`	Specifies the basis for grouping contribution-based statistics: `contributors –` group by the people who have contributed. `pages –` group by the pages used to find the contributors.
contentType	No	Both pages and blog posts	Restricts the content type that the macro will use when generating the list of contributors. Available values: `pages –` pages `blogposts –` blog posts.
`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
`templateId`	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`).
`templateName`	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.

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:

large
small

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

default-parameter

(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:

SPACEKEY:My page name

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:

BLOCK – Displays the content of the macro on a new line.
INLINE – Displays the the content of the macro as part of the same paragraph as the text preceding and following it.

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

default-parameter

(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
`width`	No	`450` pixels	The width of the gadget, using one of the following conventions: Width in pixesl, using `px` or plain numbers. For example, `500px` or `500` A percentage of the page width, using `%.` For example, `50%` Automatic resizing of the gadget to fit 100% of the page width: `auto`
`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&amp;spaceKey=DOC&amp;quickfind-space=Documentation&amp;pageId=753666&amp;pageName=Documentation%20Home&amp;quickfind-page=Documentation%20Home&amp;isEditable=true&amp;isConfigured=true&amp;refresh=15&amp;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 `sort` parameter, to change the sort order from ascending to descending. Available values: `true` – Sort order is descending. `false` – Sort order is ascending.
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 `reverse` parameter. Available values: `name` – file name. `comment` – comment linked to the attached file. `date` – date/time last modified. `size` – size of the attached file.
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.
`exclude`	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. Note: The file name and file type for this parameter are case sensitive. For example, 'my picture.PNG' will not be recognised as 'my picture.png'.
`include`	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. Note: The file name and file type for this parameter are case-sensitive. For example, 'my picture.PNG' will not be recognised as 'my picture.png'.

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

true

Determines whether the macro shows or hides the user ID of the contact.

Available values:

true – User ID is shown on the page.
false – User ID is not shown on the page.

service

Yes

Not specified.

The web service that Confluence should query.

Available values:

aim – AOL Instant Messenger
gtalk – Google Talk
icq – ICQ
jabber – Jabber
msn – MSN Instant Messenger
sametime – IBM Lotus Sametime
skype – Skype
skypeme – Skype
wildfire – Openfire Server
yahoo – Yahoo! Messenger

default-parameter

(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

default-parameter

(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:

SPACEKEY:My page name

To include a blog post, specify the date as well as the title of the blog post. For example: /2010/12/01/My blog post.

You can include pages from personal spaces using ~username as the space key, where 'username' is the person's username. For example, ~jsmith:My page name.

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 icon in the title bar of the information box.
`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>

This is important information.

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>

This is my title

This is important information.

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>

This is my title

This is important information.

JIRA Issues macro

Displays a list of JIRA issues in a page.

Macro name: jiraissues

Macro body: None.

Parameter name	Required	Default	Parameter description and accepted values
`anonymous`	No	`false`	If this parameter is set to 'true', JIRA will return only the issues which allow unrestricted viewing i.e. 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. See more details below.
`baseurl`	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.
`columns`	No	By default, the following columns are shown: type key summary assignee reporter priority status resolution created updated due	A list of JIRA column names, separated by semi-colons (;). Example columns are: key, summary, type, created, fixversion, updated, due, assignee, reporter, priority, status and resolution. You can include any columns recognised by your JIRA site, including custom columns. See the JIRA documentation for a list of names.
`count`	No	`false`	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.
`cache`	No	`on`	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'.)
`height`	No	`480`	The height in pixels of the table displaying the JIRA issues. Note that this height specification is ignored in the following situations: If you set the 'renderMode' parameter (see below) to 'static'. When the JIRA issues are displayed in a PDF or Word document, in an email message or in an RSS feed.
`renderMode`	No	In formats not mentioned below, the default is 'dynamic'. The default is 'static' when the JIRA issues are displayed in a PDF or Word document, in an email message or in an RSS feed.	By default, the JIRA Issues macro offers a dynamic display with the following features: Click the column headers to sort the output. Drag and drop the columns into a different order. Temporarily remove a column from the display. View a page of issues at a time, for faster response times. Set the 'renderMode' parameter to 'static' if you want to disable the dynamic display features.
`title`	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.
`url`	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 `tempMax` argument, then the value of `tempMax` will default to 500. If your JIRA server is version 3.12 or earlier, this means that the JIRA Issues macro will return a maximum of 500 issues. If your JIRA server is version 3.13 or later, a value of 500 means that the JIRA Issues macro will return a maximum of 500 issues per page.
`width`	No	100%	The width of the table displaying the JIRA issues. Can be indicated either as a percentage (%) or in pixels (px).

Example:

<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&amp;tempMax=10</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
`directory`	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 `url` parameter if you use both. Note: When using a local drive, you must use a directory name and not the XML file itself.
`reportdetail`	No	`all`	Level of detail required in the report. Available values: `all` `fixture` `summary` `failuresonly`
`url`	Must include either the `directory` or the `url` parameter	(None)	URL of a particular test result XML file. This parameter is overridden by the `directory` parameter if you use both. For Confluence installations that require authentication, you can specify login credentials as part of this parameter, in the form of URL parameters: `os_username` — The username of a Confluence user with permission to access the JUnit test results. `os_password` — The password of the Confluence user specified in the `os_username` parameter.
`debug`	No	`false`	If the value of this parameter is `true`, the report will show the content of failures, as well as the error messages.

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
`spaceKey`	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
`id`	No	(None)	Uniquely identifies the Livesearch macro when there are more than one Livesearch macros in a page.
`spaceKey`	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

default-parameter

(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
`page`	No	Current page	Name of the page to which the multimedia file is attached.
`space`	No	Current space	Space key of the page that has the multimedia file attached.
`name`	Yes	None	File name of the multimedia file, which is attached to a Confluence page.
`width`	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.
`height`	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.
`autostart`	No	`false`	If the parameter is set to `true` then the video or audio file will start playing as soon as the page is loaded. If this option is set to `false` then the file will not play until the user clicks the icon or image on the page.

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>

Page Properties macro

Error rendering macro 'excerpt-include'

No link could be created for 'Metadata Details Macro'.

Error rendering macro 'excerpt-include'

No link could be created for '_MetadataDetailsMacroMarkup'.

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

Error rendering macro 'excerpt-include'

No link could be created for 'Details Summary Macro'.

Error rendering macro 'excerpt-include'

No link could be created for '_DetailsSummaryMacroMarkup'.

Example:

<ac:macro ac:name="detailssummary">
  <ac:parameter ac:name="label">status</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
`border`	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>

Table of Contents macro

Displays a table of contents from your page headings.

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: `none` – No list style is displayed. `circle` – The list style is a circle. `disc` – The list style is a filled circle. This is the typical bullet list, and is the one we are using in this example list. `square` — The list style is a square. `decimal` — The list is numbered (1, 2, 3, 4, 5). `lower-alpha` — The list style is lower case, alphabetised (a, b, c, d, e). `lower-roman` — The list style is lower-case roman numerals (i, ii, iii, iv, v, vi). `upper-roman` — The list style is upper-case roman numerals (I, II, III, IV, V, VI).
`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 (`type` = `list`). Use this parameter to indent the list items according to CSS quantities. For example, a value of `10px` will successively indent list heading groups by 10 pixels. Level 1 headings will be indented 10px, and level 2 headings by an additional 10px, and so on.
`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: `.*\.[1//2]` See Sun's Regex documentation for examples of constructing regular expression strings.
`type`	No	`list`	Defines the overall format of the table of contents. Available values: `list` – displays the table of contents in a vertical list. `flat` – displays a horizontal series of links. For example: [Heading 1] [Heading 2] [Heading 3].
`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 (`type` = `flat`). Use this parameter to style the display of a flat list. Available values: `brackets` – Each item is enclosed by square brackets: [ ]. `braces` – Each item is enclosed by braces: { }. `parens` – Each item is enclosed by parentheses: ( ). `pipe` – The items are separated by a pipe: \| anything – The items are separated by the value you enter. You can enter any text as a separator, for example `***`. If using a custom separator, be aware that text displays exactly as entered, with no additional white space to further separate the characters.
`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: `.*\.[1//2]` 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>

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.

Page tree

Confluence Storage Format for Macros

Anchor macro

Attachments macro

Blog Posts macro

Change-History macro

Chart macro

Chart type parameters

Chart display parameters

Chart title and label parameters

Chart data parameters

Chart colour parameters

Chart axis parameters

Pie chart Parameters

Chart attachment parameters

Cheese macro

Children Display macro

Code Block macro

Column macro

Content by Label macro

Content by User macro

Content Report Table macro

Contributors macro

Contributors Summary macro

Create from Template macro

Create Space Button macro

Excerpt Include macro

Excerpt macro

Expand macro

Favourite Pages macro

Gadget macro

Gallery macro

Global Reports macro

HTML Include macro

HTML macro

IM Presence macro

Include Page macro

Info macro

JIRA Issues macro

JUnit Report macro

Labels List macro

Livesearch macro

Loremipsum macro

Multimedia macro

Page Properties macro

Page Properties Report macro

Section macro

Table of Contents macro

Macro format notes

Macro bodies

Plain text bodies

Other notes