list-pages macro

Let's start with a simple example: listing all ancestor pages (i.e. parent, parent's parent, etc. all the way to the root of the current space).

List of all parent pages (from the current page)

 List of all parent pages (from the current page):
{list-pages:direction=up}

Which results in:

List of all parent pages (from the current page):

Unknown macro: {list-pages}

As you can see, each page in the space's hierarchy, from the current up to the top (root) is listed as a link to the page itself.

Similarly, we can list all children, and children's children pages from the current page, much like the {children} macro does, but then recursively (at infinite depth):

 List of all children pages (from the current page):
{list-pages:direction=down}

Which results in:

List of all children pages (from the current page):

Unknown macro: {list-pages}

You may specify the page at which the {list-pages} macro should start searching. By default (if nothing is specified) this will be the current page.

For instance, to list all pages in a space, specify the spacekey: as the parameter for startPage as follows:

 List of all children pages in the [Builder|Builder:] space
{list-pages:direction=down|startPage=Builder:}

Which results in:

List of all children pages in the Builder space

Unknown macro: {list-pages}

You can set the {list-pages} macro to search for pages in more than one space.

By default, the macro will search for pages in the current space. You can specify a different space with startPage=spacekey: as per the example above. Additionally, you can specify a list of spaces to search in:

 List of pages in the [Builder|Builder:] and [Bubbles|Bubbles:] spaces:
{list-pages:direction=down|startPage=@home|space=Builder,Bubbles}

Which results in:

List of pages in the Builder and [Bubbles] spaces

Unknown macro: {list-pages}

The {list-pages} macro can retrieve pages based on their names (page titles). For this, use the following syntax:

 List of pages titled "Panel Macros", "Menu Macros", or "Utility Macros" in the [Builder|Builder:] space:
{list-pages:direction=down|startPage=Builder:|title=Panel Macros,Menu Macros,Utility Macros}

Which results in:

List of pages titled "Panel Macros", "Menu Macros", or "Utility Macros" in the Builder space:

Unknown macro: {list-pages}

The {list-pages} macro can be used to list pages containing any one label in the list specified. Pages listed by the macro will have at least one of the labels.

 List of pages labeled 'builder' or 'theme':
{list-pages:direction=down|label=builder,theme}

Which results in:

List of pages labeled 'builder' or 'theme':

Unknown macro: {list-pages}

A list of metadata keys, or key:value pairs, can be given to the {list-pages} macro as search criterion.

If you specify a key:value pair, then the macro will return only pages containing both that key and the specific value for that key. If you only specify a key then the macro will return all pages containing that key, regardless of the value.

See the Metadata plugin page for more information on the Metadata plugin and key:value pairs.

 List of pages authored by [~gfraser] in the [Builder|Builder:] space:
{list-pages:direction=down|startPage=Builder:|metadata=author:gfraser}

Which results in:

List of pages authored by [~gfraser] in the Theme Builder Plugin space:

Unknown macro: {list-pages}

In order to prevent the macro from returning an empty list in case no pages are found meeting the given search criteria, you may specify a default page to return.

 List of parent pages:
{list-pages:direction=down|startPage=@root|default=@home}

Which results in:
List of parent pages:

Unknown macro: {list-pages}