The {children} macro displays lists of child pages attached to the current page or orphan pages that are not attached to any page...

Properly organised sites use hierarchies of pages - a bit like a family tree where child pages are related to their parent pages and so on:

The {children} macro is one of the most flexible ways to display the hierarchy of pages for any part of your site, or even display pages that are not attached to a parent page.

Add the macro to your page as follows:

{children:all=true|depth=x|style=headingStyle|excerpt=true|page=parent|first=num|
sort=mode|reverse=true}

Parameters

Parameter	Required	Default	Notes
all		false	If this parameter is set to true then all child pages (with all of thier child pages) will be shown.
depth		1	Use this parameter to choose how many levels of the page hierarchy will be shown (or use the "all" parameter to show all of them).
style			Normally, an unordered list is used to display pages, however you can use this parameter to output the top level of child pages using one of the standard heading styles (h1, h2, h3, h4, h5, h6).
excerpt		false	By default, only the page titles are shown unless you set this parameter to true in which case excerpts are shown alongside the page titles.
page			By default, the list of child pages is shown starting with the current page. You can use this parameter to start from a different page if desired.
first			Sometimes a page may have vast number of child pages attached to it - if so, you might want to use this parameter to specify the maximum number of pages that are output.
sort		title	Pages are normally sorted alphabetically on their title, but you can also sort them by their creation or modified dates.
reverse		false	Set this parameter to true to reverse the sort order of pages.

This macro is part of the standard Confluence Distribution.

© 2005 Atlassian Software Systems Pty Ltd.

This macro is part of the standard Confluence distribution.

For the full set of features listed in this tutorial, such as sorting, you should upgrade to at least Confluence 1.4.4.

There is currently no dedicated issue tracking project for this plugin.

• Altassian's online documentation
• noparent macro
• incoming-links macro
• [USERGUIDE:recentpages macro]
• [USERGUIDE:recently-udpated macro]
• [USERGUIDE:blog-posts macro]

Basic Use

List the pages attached to the current page:

{children}

The result is shown below (we added a single child page to this page):

• Example Child Page

Note:
If the page has no child pages, nothing will be shown.

Displaying Excerpts

If you are in the habbit of defining excerpts for pages, you can display them using the "excerpt" parameter:

{children:excerpt=true}

Resulting in:

• Example Child Page — This page exists only to aid the example on the parent page which discusses the children macro...

Displaying All Child Pages

You can display all child pages, and their child pages, etc., with the "all" parameter:

{children:excerpt=true|all=true}

Resulting in:

• Example Child Page — This page exists only to aid the example on the parent page which discusses the children macro...
  • Another Example Child Page — This page exists only to aid the example of the all parameter in the children macro...

Alternate Starting Page

Display child pages for a specific parent page using the "page" parameter, such as our Macros page for example:

{children:page=Macros}

The result is shown below:

• Advanced — Advanced macros enable you to add custom HTML and scripting to your content...
• Basic Formatting — Basic Formatting macros allow you to change text colour, put content in panels and other basic formatting requirements...
• Games — Add brain-taxing games to Confluence...
• Generic Macros — These Generic macros haven't yet been classified in to a specific category, but you'll find some amazing things here...
• Layout — Layout macros are used to arrange content in to panels, columns and block quotes...
• Navigation and Lists — Navigation and List macros provide additional navigation elements and lists of content, etc...
• Theme Builder Macros
• Users and Personalisation — User and Security macros display users lists and also allow content to be filtered depending on the logged in user...

Limiting Number of Pages

Sometimes you might only want to show a limited number of child pages. To do this, use the "first" parameter and specify how many pages to show:

{children:excerpt=true|page=Macros|first=2}

The result is shown below:

• Advanced
• Basic Formatting

Note:
This only limits the number of child pages shown at the top level - if you are showing additional levels (see next example) then the limit will not apply to those additional levels.

Displaying Specific Number of Levels

The "depth" parameter allows you to specify how many levels of child pages to show:

{children:excerpt=true|page=Macros|first=2|depth=2}

The result is shown below:

• Advanced
  • add-label macro
  • alias macro
  • create-page macro
  • div macro
  • html macro
  • html-tag macro
  • redirect macro
  • span macro
  • style macro
• Basic Formatting
  • align macro
  • bgcolor macro
  • center macro
  • code macro
  • color macro
  • copyright macro
  • highlight macro
  • loremipsum macro
  • noformat macro
  • quote macro
  • reg-tm macro
  • sm macro
  • strike macro
  • tm macro

Custom Heading Styles

The "style" parameter allows you to use a heading style for the first level of child pages, ideal for creating contents pages:

{children:excerpt=true|page=Macros|first=2|depth=2|style=h3}

The result is shown below:

Advanced

Advanced macros enable you to add custom HTML and scripting to your content...

• add-label macro — The {add-label} macro allows you to add one or more labels to a page automatically.
• alias macro — The {alias} macro allows you to create aliases (or shortcuts) for pages...
• create-page macro — The {create-page} macro asks the user for the name of the page and then creates it based on a template...
• div macro — The {div} macro wraps content in a div tag with optional class and styles...
• html macro — The {html} macro allows you to add raw HTML to your pages, but should be used with care...
• html-tag macro — The {html-tag} macro provides a safe mechanism for the addition of specific HTML tags and attributes to be inserted in to your content...
• redirect macro — The {redirect} macro will automatically redirect the browser to an alternate web page either within your own site or on an external site...
• span macro — The {span} macro wraps content in a span tag with optional class and styles...
• style macro — The {style} macro allows you to add custom style sheets to a page or import from an external URL...

Basic Formatting

Basic Formatting macros allow you to change text colour, put content in panels and other basic formatting requirements...

• align macro — The {align} macro allows you to quickly and easily set the alignment of content...
• bgcolor macro — The {bgcolor} macro allows you to change background colour of a block of content...
• center macro — The {center} macro allows you to quickly and easily center content...
• code macro — The {code} macro is used to display syntax highlited source code...
• color macro — The {color} macro allows you to change text colour quickly and easily...
• copyright macro — The {copyright} macro makes it easy to add customisable copyright marks to your content...
• highlight macro — The {highlight} macro allows you to change background colour of a section of content...
• loremipsum macro — The {loremipsum} macro adds latin text to your page, useful for testing purposes...
• noformat macro — The {noformat} macro is used to display unformatted text on your pages...
• quote macro — The {quote} macro is used to group blocks of content quickly and easily...
• reg-tm macro — The {reg-tm} macro makes it easy to add customisable registered trademarks to your content...
• sm macro — The {sm} macro makes it easy to add customisable service marks to your content...
• strike macro — The {strike} macro provides a highly graphical way to indicate deleted text...
• tm macro — The {tm} macro makes it easy to add customisable trademarks to your content...

Sorting Pages

The "sort" parameter allows you to change the sort order used when listing pages. By default, pages are sorted alphabetically on their title:

{children:first=4|page=Basic Formatting|sort=title}

The result is shown below:

• align macro
• bgcolor macro
• center macro
• code macro

You may however prefer pages to be chronologically sorted by their creation date:

{children:first=4|page=Basic Formatting|sort=creation}

The result is shown below:

• color macro
• bgcolor macro
• center macro
• quote macro

Or chronologically sort them on the date they were last modified:

{children:first=4|page=Basic Formatting|sort=modified}

The result is shown below:

• align macro
• bgcolor macro
• loremipsum macro
• color macro

Reversing Sort Order

The "reverse" parameter allows you to reverse the sort order for pages:

{children:excerpt=true|page=Basic Formatting|sort=title|reverse=true}

The result is shown below:

• align macro — The {align} macro allows you to quickly and easily set the alignment of content...
• bgcolor macro — The {bgcolor} macro allows you to change background colour of a block of content...
• center macro — The {center} macro allows you to quickly and easily center content...
• code macro — The {code} macro is used to display syntax highlited source code...
• color macro — The {color} macro allows you to change text colour quickly and easily...
• copyright macro — The {copyright} macro makes it easy to add customisable copyright marks to your content...
• highlight macro — The {highlight} macro allows you to change background colour of a section of content...
• loremipsum macro — The {loremipsum} macro adds latin text to your page, useful for testing purposes...
• noformat macro — The {noformat} macro is used to display unformatted text on your pages...
• quote macro — The {quote} macro is used to group blocks of content quickly and easily...
• reg-tm macro — The {reg-tm} macro makes it easy to add customisable registered trademarks to your content...
• sm macro — The {sm} macro makes it easy to add customisable service marks to your content...
• strike macro — The {strike} macro provides a highly graphical way to indicate deleted text...
• tm macro — The {tm} macro makes it easy to add customisable trademarks to your content...

You can use this, along with the "sort" and "first" parameters, to list the most recently updated page, for example:

{children:excerpt=true|page=Basic Formatting|reverse=true|sort=modified|first=1}

Which results in:

• center macro — The {center} macro allows you to quickly and easily center content...

Displaying Orphan Pages

Pages that don't have a parent page are referred to as "orphans". You can display a list of orphan pages in the current site as follows:

{children:page=/}

The result is shown below:

• Documentation
• Space
• Home
• Tabs
• Forum
• Shop

Note:
If the page on which you use this macro is itself an orphan, it will not be included in the list.

You can also display orphan pages for another site by specifying the space name as follows:

{children:page=ADAPTAVIST:}

This will show all orphan pages in the ADAPTAVIST space (which is where our adaptavist.com site lives):

• Home
• Bookshelf
• Donation Received
• Payment Cancelled
• Payment Methods
• Payment Received
• Paying Us
• Donate
• Contest Terms and Conditions
• Apply Online

See Also: noparent macro