2023-11-30 12 Days of Confluence Elements

Owned by Denise Kidd
Last updated: Oct 31, 2024
22 min read

Welcome to the 12 Days of Confluence Elements! Each day you’ll learn how to use common elements we use in our Confluence instance. Along with the text you add to a page, elements are the building blocks that help you organize and present information in the way you want.

What are elements?

All the items that can be inserted onto a page are elements. Elements include panels, dividers, emojis, macros. We’ll learn more about macros soon.

Adding an element

Elements can be added by clicking the Insert menu from the toolbar, or from the slash command menu.

In our instance

We use elements such as panel, divider, emoji, expand, and heading, and macros. You can see examples of many of these elements at Graduation & Commencement.

What are macros?

A macro is a type of element that allows you to extend the capabilities of your Confluence pages, allowing you to add extra functionality or include dynamic content. For example, use the Attachments macro to list files attached to a page. Macros can also be used to create visual interest.

Add a macro to your page

 

To add a macro:

  1. When editing, select the Insert icon.

  2. Find the macro by name and select it

  3. Configure it as needed

You can also type / on the page to bring up the same list you'd see by selecting the Insert icon from the toolbar. Continue typing the name of the macro to filter the list.

To edit a macro:

  1. Select the macro placeholder.

  2. Select the Edit icon to open the configuration panel.

  3. Configure the parameters. Your changes are saved as you go.

  4. Resume editing the page, and the panel closes.

You can also select the centered , medium-width , and full-width icons to adjust the width of some macros. Select the trashcan icon to remove the macro.

Macro parameters

Many macros have optional parameters you can use to control the macro's output.

With the Attachments Macro, for instance, you have two optional parameters allowing you to:

  • Specify the file formats of the attachments displayed

  • Choose whether or not you want old versions of the attachments displayed

Macro placeholders

Macro placeholders are displayed in the editor where you have added a macro to the page.

When editing a page, you can:

  • Double-click a macro placeholder (or click the placeholder and choose Edit) to open the macro dialog window and edit the macro's parameters

  • Select a macro placeholder to cut, copy and paste the macro

Use the Children Display macro to insert a list of a page’s child pages, and their descendants. People viewing the page will only see the links for pages they have permission to view.

By default, the list will show the child pages of the page the macro is on — but you can also select a different parent page when configuring the parameters. The macro can display the child and descendant pages of whatever parent page is specified.

When would you use Children Display macro?

This is useful, for example, if you want to create navigation links on a parent page to its nested pages.

Where is this used in our instance?

You can find Children Display macros on section landing pages such as Graduation & Commencement under “In this section”.

 

Add the Children Display macro

To insert a macro:

  1. When editing, select Insert from the toolbar

  2. Find the macro by name and select it

  3. Configure it as needed

You can also type / on the page to bring up the same list you'd see by selecting from the toolbar. Continue typing the name of the macro to filter the list.

To edit a macro:

  1. Select the macro placeholder.

  2. Select the Edit icon to open the configuration panel.

  3. Configure the parameters. Your changes are saved as you go.

  4. Resume editing the page, and the panel closes.

The page links are dynamic — if additional child pages are published or the page titles are edited, those changes will automatically be reflected in the list.

Configure the parameters

Parameters are options that you can set to control what and how content from the macro appears on the page. 

If the parameter name used in Confluence Cloud storage format or wikimarkup is different than the label used when inserting macros using the browser or the slash command, it will be listed below in brackets (example).

Parameter

Default

Description

Parameter

Default

Description

Show Descendants
(all) 

not selected

Select this if you want to display all of a page’s children and their descendants.

Links to all the nested pages will be shown, without needing to specify the Depth of Descendants.

Parent Page
(page) 

current page

If the page you’re on is the parent of the pages you want to list, you can leave this field empty.

But the macro can display child and descendant pages of whatever parent page is specified.

Type to search for a page, by name, from any space. You can also try typing these shortcuts:

  • '/' — to list the top-level pages (those without parents).

  • 'pagename' — to list the children of the specified page.

  • 'spacekey:' — to list the top-level pages of the specified space.

  • 'spacekey:pagename' — to list the children of the specified page in the specified space.

Number of Children
(first) 

no limit

This field limits the number of children shown. Leave it empty if you want to show all child pages.

If you have a particularly long list, you can shorten it by entering the exact number of child pages to display.

Descendants of any child pages shown will still be displayed, if you’ve set the Depth of Descendants to include them.

Depth of Descendants
(depth) 

only child pages

This field controls whether to include the child page’s descendants, and if so, how many levels.

If you only want to show the parent’s child pages, either leave it empty, or enter the number 1 to specify one level of page descendants.

Enter the number 2 to specify two levels of page descendants (child, grandchild). And so on.

Heading Style
(style) 

none (bullets)

If you leave this field empty, the pages default to a bulleted list.

If you’d like the child pages to be formatted as headings, select a heading level.

This is also a way to increase the font size. Descendants of child pages, however, will still show up as indented bullets in the normal size and style of text.

Excerpt Display
(excerpt) 

none

If you only want to show page title links, leave this set to “none”.

But you also have the option to include a page preview under each page in the list:

  • None - no preview will be displayed

  • Simple - displays the first line of text contained in an Excerpt macro on any of the listed pages. If there isn’t an Excerpt macro on the page, nothing will be shown.

  • Rich content - displays either the full contents of an Excerpt macro (if the page has one) — or the first part of the page content including formatted text, images, and some macros.

Sort Children By
(sort) 

Manual if manually ordered, otherwise alphabetical

Optional. Choose:

  • creation — to sort by content creation date

  • title — to sort alphabetically on title

  • modified — to sort by last modification date.

Reverse Sort
(reverse) 

false

Use with the Sort Children By parameter. When set, the sort order changes from ascending to descending.

The Content by Label macro is used to display lists of pages, blog posts or attachments that have particular labels.  

When would you use Content by Label macro?

It's great for collecting related pages together and filtering out content that you don't want to see.

For example, you could use this macro to display a list of all pages that have the label 'feature-shipped' and include the word 'Blueprint', or to list any pages with the label 'meeting-notes' that you've been mentioned in.

Here's how the macro looks on your page:

 

Where is this used in our instance?

Many articles include the Content by Label macro to drive users to related content. Our configuration ranges from displaying all content with a selected label to displaying only 5 articles with a link to additional related content. You can see it in action on Graduation & Commencement, and this macro can be used on any page where it makes sense to provide additional related content.

 

Use the Content by Label macro

To add the Content by Label macro:

  1. When editing, select Insert from the toolbar

  2. Find the macro by name and select it

  3. Configure it as needed

To edit the Content by Label macro:

  1. Select the macro placeholder.

  2. Select the Edit icon to open the configuration panel.

  3. Configure the parameters. Your changes are saved as you go.

  4. Resume editing the page, and the panel closes.

CQL filters

CQL (Confluence Query Language) is a query language developed for Confluence, which you can use in some macros and the Confluence search. Confluence search and CQL-powered macros allow you to add filters to build up a search query, adding as many filters as you need to narrow down the search results. To add a filter to your query, select the Add a filter link.

You can use the following CQL filters:

Filter

Description

Operators

Filter

Description

Operators

Label*

 

Returns pages, blog posts or attachments with these labels.

OR (multiple values in the same filter)

AND (multiple Label filters)

With ancestor

Returns pages that live under this page in the page tree.

This allows you to restrict the macro to a single page tree.

OR (multiple values in the same filter)

Contributor**

Returns pages or blog posts that were created or edited by these people.

OR (multiple values in the same filter)

Creator

Returns items created by these people.

OR (multiple values in the same filter)

 

Mentioning user

Returns pages and blog posts that @mention these people.

OR (multiple values in the same filter)

With parent

Returns only direct children of this page (further sub-pages won't be included)

EQUALS (one page only)

In space**

Returns items from these spaces.

OR (multiple values in the same filter)

Including text**

Returns items that contain this text.

CONTAINS (single word or phrase)

With title

Returns items that contain this text in the title.

CONTAINS (single word or phrase)

Of type**

Returns only pages, blogs or attachments.

OR (multiple values in the same filter)

AND, OR, and NOT operators

  • For an OR search, specify multiple values in the same field.
    So to show pages with 'label-a', 'label-b' or both you'd put 'label-a' and 'label-b' in the same Label field, like this:

  • For an AND search, add more than one filter and specify a single value in each.
    To show only pages with label-a and label-b you'd put 'label-a' in one label field, then add a second Label field to the macro, and put 'label-b' in the second one, like this:

Put simply, OR values are entered in the same filter, AND values are entered in different filter. 
Only some filters support AND. If the filter doesn't support the AND operator, you won't be able to add that filter more than once.  

  • For a NOT search, enter a minus sign (-) before the label. This'll exclude everything with that label.

  • This field is required in CQL-powered macros.

** You can add these filters in CQL-powered macros but in search they're part of the standard search filters, so they don't appear in the Add a filter menu.

 

Macro display options

These options control how the macro appears on your page.

Parameter

Default

Description

Parameter

Default

Description

Sort by

Modified

Sort the list by title, the date it was created, or the date it was last modified. If you don't select an option, CQL default ordering by relevancy is used.

Reverse sort

False

Sort the list descending instead of ascending (Z - A, earliest - latest)

Maximum number of pages

15

Limit the number of items to include in the list. This can be any value up to 500 pages.

List title

Blank

Include an optional heading for the macro

Show labels for each page

True

Show or hide the labels applied to each item

Show space name for each page

True

Show or hide the space name for each item

Display excerpts

False

Allows you to include a short excerpt under each page in the list. Choose between:

  • None - no excerpt will be displayed.

  • Simple - displays the first line of text contained in an Excerpt macro any of the returned pages. If there is not an Excerpt macro on the page, nothing will be shown.

  • Rich content - displays the contents of an Excerpt macro, or if there is not an Excerpt macro on the page, the first part of the page content, as formatted text, including images and some macros.

 

The Table of Contents macro scans the headings on the current Confluence page to create a table of contents based on those headings.

When would you use Table of Contents macro?

This helps readers find their way around lengthy pages, by summarizing the content structure, and by providing links to headings. A rule of thumb is to use the Table of Contents macro when your article requires scrolling past the “fold” of a page. Users generally familiar with the page may be looking for a specific section, and the Table of Contents macro can help them navigate to the specific content they’re looking for.

Where is this used in our instance?

An example of the Table of Contents macro is found on Viewing and maintaining a student's academic standing (SHAINST/SGASTDN). Rather than using a formatted heading for “On this page”, we use bolded Normal text to prevent the heading from pulling into the macro.

 

Use the Table of Contents macro

To add a Table of Contents to your page: 

  1. From the editor, select Insert from the toolbar to bring up the insert menu.

  2. Find the Table of contents macro and select it. You can also type /tableofcontents to select this macro from the insert menu right in the body of your page.

  3. Upon selection, the Table of Contents placeholder will appear in the body of your page.

  4. Your table of contents won’t be visible while editing. When you preview the page or publish it, you’ll be able to see an auto-generated table of contents based on the page’s headings.

 

To configure your Table of Contents: 

  1. From the editor, select the Table of Contents placeholder.

  2. Select the Edit () icon to open the configuration panel.

  3. Customize the parameters of your table of contents in either Basic or Advanced mode.

  4. Your selections won’t be visible while editing. When you preview the page or publish it, you’ll be able to see how your customized table of contents looks.

  5. As you continue editing the page, the configuration panel will close.

Parameters

Parameters are options that you can configure to control exactly how your table of contents appears on the page. 

To customize your table of contents, you can configure its basic and/or advanced parameters, depending on your needs and preference.

Basic parameters

Basic parameter

Default

Description

Example

Basic parameter

Default

Description

Example

Display as

Vertical list

  • Vertical list — produces a typical list-type table of contents.

  • Horizontal list — produces a flat, horizontal menu-type series of links.

Bullet style

Bullet

This parameter applies to vertical lists only.

Select from any of the following values:

  • None — no bullets are displayed

  • Mixed —  the bullet style is a mix of shapes, filled and open

  • Bullet — the bullet style is a filled circle.

  • Circle —  the bullet style is an open circle

  • Square — the bullet style is a filled square

  • Numbered — the list is numbered (1, 2, 3, 4, 5)

Separate sections by

Bracket

This parameter applies to horizontal lists only.

Select from any of the following values:

  • Bracket — Each item is enclosed by square brackets: [ ]

  • Brace — Each item is enclosed by braces: { }

  • Pipe — Each item is separated by a pipe: |

Include heading levels from [#] to [#]

1-6

Select the minimum and maximum heading levels to include in your table of contents.

Include section numbers

Unchecked

Select the checkbox to apply outline numbering to your headings. (Example: 1.1, 1.2, 1.3)

Advanced parameters

Advanced parameter

Description

Advanced parameter

Description

Indent headings
(indent) 

Sets the indent for a vertical list according to a valid CSS unit value.

Entering 10px will successively indent heading groups by 10px. Level 1 headings will be indented 10px and level 2 headings will be indented an additional 10px.

Include Headings with:
(include) 

Filter headings to include in your table of contents by inputting specific criteria. You can use wildcard characters.

If you only want the Overview and Summary headings to appear, enter Overview|Summary in this field.

 

Exclude Headings with:
(exclude) 

Filter headings to exclude from your table of contents by inputting specific criteria. You can use wildcard characters.

If the headings you want to exclude are Overview and Summary, enter Overview|Summary in this field.

 

CSS class name
(class) 

If you have custom TOC styles in your CSS style sheet, use this parameter to output the TOC inside <div> tags with the specified class attribute.

Exclude in PDF export
(printable) 

If the box is checked, the TOC will not be visible when you export the page to PDF and/or print it.

Other ideas

Managing mirrored content - Save time by reusing content

Standardize content with page templates - Use page templates

Review the history of a page - View page history

Managing draft content - Draft your work

Help users find new content with Live Search - Insert the Live Search macro