Children Display Macro

This macro is available in Confluence Server and Data Center. Learn about the macros available in Confluence Cloud.

Add the Children Display macro to a page to display a list of pages from a specific part of the page hierarchy.  You can choose to display pages that are a child of the current page, or a child of any other page in a space. 

This macro is great for providing quick access to:

  • pages related to a project 
  • procedures and how-to pages.

Because it relies on the page hierarchy, the list of pages is automatically updated when pages are added, deleted, or moved.  You can even show an excerpt from the page for extra context. 

On this page:

Screenshot: The Children Display macro, showing a list of pages about printers.

Want to create a table of contents from headings on your page? See Table of Contents Macro

Add the Children Display macro to your page

To add the Children Display macro to a page:

  1. From the editor toolbar, choose Insert > Other Macros.
  2. Choose Children Display from the Confluence content or Navigation category.
  3. Use the parameters below to specify which pages to display, and how you want them to look. 
  4. Choose Insert

You can then publish your page to see the macro in action. 

Screenshot: Specifying the parent page and display options in the Children Display macro.

Change the macro parameters

Macro parameters are used to change the behaviour of a macro.

To change the macro parameters:

  1. In the editor, click the macro placeholder and choose Edit.
  2. Update the parameters as required then choose Insert.

Here's a list of the parameters available in this macro. 




Show Descendants


Choose whether to display all the parent page's descendants.

If true shows the complete tree of pages underneath the parent page, regardless of Depth of Descendants

Parent Page


Specify the page to display children for, from either the current space or a different space. Enter:

  • '/' — to list the top-level pages of the current space, i.e. 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


Restrict the number of child pages that are displayed at the top level.

Your administrator may enforce a maximum number for this parameter.

Depth of Descendants


Enter a number to specify the depth of descendants to display. For example, if the value is 2, the macro will display 2 levels of child pages.

This setting has no effect if Show Descendants is enabled.

Your administrator may enforce a maximum number for this parameter.

Heading Style


Choose the style used to display descendants.

Include Excerpts


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 on 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 including formatted text, images, and some macros.

Note that your administrator may have set this parameter to none for it to apply to the whole site.

For admin-use only

(info) The JVM paramater confluence.child-macro.disable-excerpt can be set to "true" to disable excerpts in children display macros. See Recognized System Properties for more details on this parameter and when it can be used.

Sort Children By

Manual if manually ordered, otherwise alphabetical

Leave blank to display pages in the order they currently appear in the page tree. Alternatively, choose:

  • creation — to sort by content creation date
  • title — to sort alphabetically on title
  • modified — to sort of last modification date.

Reverse Sort


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

Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro browser, it will be listed below in brackets (example).

Other ways to add this macro

Add this macro as you type

Type followed by the start of the macro name, to see a list of macros. 

Add this macro using wiki markup

This is useful when you want to add a macro outside the editor, for example as custom content in the sidebar, header or footer of a space.

Macro name: children

Macro body: None.

tip/resting Created with Sketch.

Do more with Confluence

Extend Confluence with one of the hundreds of other macros in the Atlassian Marketplace. Here are a couple for organizing your Confluence page: 

Last modified on Dec 11, 2023

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.