Annual Documentation Survey

Do you have 4 minutes to help us improve our documentation? Please take our annual survey!

Skip to end of metadata
Go to start of metadata

The {list-pages} macro generates a list of pages based on the parameters given to it.

It allows listing pages based on:

  • a specific page name,
  • page hierarchy (parent/child relationships),
  • page labels, and
  • metadata keys or key:value pairs which the pages must have.

The macro searches for pages based on these properties in the current space by default, or in any number of spaces which can be specified in the macro parameters.

If more than one search criterion is specified (e.g. labels and metadata), then only pages meeting all the selection criteria will be returned and listed by the macro (boolean AND relationship between the search criteria). Within a list of search terms (e.g. list of labels or metadata), any page matching at least one of the items in the list will be returned (boolean OR relationship within search terms).

Finally, if no page is found satisfying the selected parameters, a default page can be specified to be listed by the macro instead.

See also the list-* macros page for an overview.

Requirements

This macro requires Builder 3.0 or above.

Usage

 {list-pages:direction=ancestors|startPage=My Page|space=DOC|title=Page 1,Page 2|label=test,label2|metadata=key1,key2:value1,key2:value2|default=Default Page} 

Examples of common structures can be found in the examples below.

Parameters

Property

Required

Default

Notes

direction

(tick)

 

The direction (in page hierarchy) that the macro should look in when searching for pages. The following values are permitted:

  • ancestor/ancestors/up - search for pages amongst the ancestors of the start page
  • descendant/descendants/descendents/down - search for pages amongst the descendants of the start page
  • sibling/siblings - search for pages amongst the siblings of the start page
  • children - search for pages amongst the children of the start page
  • none - don't search, just use the start page

startPage
or
startFrom

(error)

@self

The page to start the search from. The following values are permitted:

  • @self - the current page (default)
  • @root - the root of the current page's tree
  • @parent - the parent of the current page
  • @home - the homepage of the current space
  • pagetitle - a named page (either the page title, or spacekey:title)

space

(error)

 

Comma-separated list of spaces to search in

title

(error)

 

Comma-separated list of page titles to search for

label

(error)

 

Comma-separated list of labels the page(s) should have

metadata

(error)

 

Comma-separated list of metadata key:value pairs, or metadata keys which the pages must posess. If a key:value pair is specified, then the key must have that value; if only the key is specified then any value is valid

default

(error)

 

Specifies a default page to use if no page was found with the previous search parameters. The following values are permitted:

  • @self - the current page (default)
  • @root - the root of the current page's tree
  • @parent - the parent of the current page
  • @home - the homepage of the current space
  • pagetitle - a named page (either the page title, or spacekey:title)

Examples

 List ancestor pages

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.

 List all children pages

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}
 Specifying the starting page for the search

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}
 Searching in more than one space

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}
 List all pages with specific names

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}
 List pages with given labels

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}
 List pages with given metadata

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}
 Specifying a default page to return

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}

Hints and Tips

None at present.

Frequently Asked Questions

None at present.

6 Comments

  1. Unknown User (dhodge@acteksoft.com)

    when using the list-pages macro to search across spaces I only get results for the current space. we are using confluence 3.3

    Unknown macro: {list-pages}
    1. Unknown User (suedti)

      I can confirm this behavior on Conf 3.3

      1. Unknown User (kbrophy)

        Hi Dean, Philipp,

        I have confirmed this as a bug and have raised it on our internal issue tracker for further review by the development team.

        Regards,
        Keith

  2. Unknown User (jersaunders)

    When using the Start Page option, if using the Macro dialog to add list-pages to your page, it incorrectly uses the property "startpage=" instead of "startPage=". If you manually correct the case of the 'P', it should work.

    1. Unknown User (kbrophy)

      Hi Jerren,

      Thanks for this report - I have raised an internal issue with our developers.

      Cheers,
      Keith

  3. Unknown User (myrmecophaga)

    How do I sort the listed pages? I want my list of pages to be alphabetical. Currently, when I use list pages direction = siblings, I get a list, but it's never sorted alphabetically.

    Thanks,
    Gregory