Documentation for Confluence 5.5.
Documentation for Confluence Cloud and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

Use the Children Display macro to list the child pages of a page and the further descendants (children's children). By default, the macro displays links to the child pages as shown in the screenshot below. People viewing the page will see only the links for pages that they have permission to view.

Screenshot: The Children Display macro in Confluence

Using the Children Display macro

To add the Children Display macro to a page:

  1. In the Confluence editor, choose Insert > Other Macros.
  2. Find and select the required macro.

Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of suggested macros. Details are in Using Autocomplete.

To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open, where you can edit the parameters of the macro.

Example

This list of child pages is generated by a Children Display macro on this page:

Parameters

Parameters are options that you can set to control the content or format of the macro output. 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).

Parameter

Default

Description

Show Descendants
(all

false

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
(page

current

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
(first

none

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

Depth of Descendants
(depth

none

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 of Show Descendants is enabled.

Heading Style
(style

none

Choose the style used to display descendants.

Include Excerpts
(excerpt

false

Display excerpts for the child pages, if they exist.

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 of last modification date.

Reverse Sort
(reverse

false

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

Code examples

The following examples are provided for advanced users who want to inspect or edit the underlying markup for a Confluence page. 

Macro name: children

Macro body: None.

Storage format example

Wiki markup example

  • No labels

58 Comments

  1. Anonymous

    is there a way to change/replace the  Children with Page ???

    (Children (2)   Hide Children  |  View in Hierarchy   )

    like

    Page  (2)   Hide Page |  View in Hierarchy

    please help!

    1. Hi,

      In your i18n settings (internationalization). You can change the following setting from:

      to this:

      This could be done at a Confluence level or a theme level. For more information on how to change it at a theme level have a look at this page: http://confluence.atlassian.com/display/DISC/i18n+in+Confluence+Plugin+Development

      Regards,
      Jason Hinch

  2. Anonymous

    Hi,

    Sometimes you want to list all the children except one or two. Is there no way to do this in a easy way? E.g. by using labels.

    -Ívar

    1. Hi Ívar,

      Perhaps, you might want to vote on the following feature requests:

      Cheers,
      Azwandi

  3. Hi there,

    I have been using the children macro for displaying bookmarks (children:page=.bookmarks) on a summary page. (the children macro has a neater layout than the bookmarks macro for our purposes).

    Is there any way of displaying bookmarks by label, using the children macro (or a macro which produces a similar layout)?

    We have 8 different sub-section to what now is growing into a very big space, and would like to show bookmarks relevant only to each subsection in our lists of bookmark.

    Cheers,

    Ollie

    1. Hi Ollie,

      Is there any way of displaying bookmarks by label

      This can be done by using the {bookmarks} macro. Set all the other parameter to false except the showLabels parameter.

      macro which produces a similar layout

      1. In order to get similar layout, browse to Confluence installed directory->Conf x.x.x->database->bundled-plugins
      2. Look for socialbookmarking-x.x.x.jar file. Refer here on how to edit jar file.
      3. You need to change the appropriate .vm file in the jar file to modify the layout.

      Hope that helps.

      Cheers,
      Komathi

  4. Anonymous

    Hi,

    I want to display the childrens text on the parent page, at the moment I do this by using the include command

    Unable to render {include} The included page could not be found.

    I sometimes have 20+ children that I need to include and it gets a bit tedious so I would like to know if there is a command I can use to include all the text.

    1. I am sorry that I cannot think of any features/plugins in existence that could cater for this requirement. You might want to raise a feature request or try Atlassian Answers.

    2. Anonymous

      I'm in need of the same macro as I am doing the same:

      [child 1]

      Unable to render {include} The included page could not be found.

      [child 2]

      Unable to render {include} The included page could not be found.

      I'm doing this such that each child is searchable as a result

      anyone?

      1. Hi,

        I am not too sure on the question. I presume that you want to have a way so that whenever you put child 1, then it will render as {include:child 1}. If so, Confluence seems to not have such feature. However, you can use a user macro to generate another macro (including macro plugin).

        Cheers,

  5. Anonymous

    I'd like the feature to sort the children in an arbitrary order.. say the children are sub topics in a book. Currently I would have to name the pages "00 Topic A", "01 Something else" etc..

    Perhaps each page could define a sort order as meta data e.g.

    Unknown macro: {sortorder}

    1

    etc... would be a good way to do this...

    Thanks

    1. Hi,

      As far as I know, this feature is not currently available in Confluence. However, I have found a similar improvement request. Please add yourself as a watcher, vote for this improvement and add your own comments to this request. For further details on how we include new features and improvements, you might want to read this page

      Cheers
      JSashi

  6. Anonymous

    Hi,

    Is there any way to automatically display a list of child-pages, sorted by label contents, on the parent-page?

    Thanks

    1. Hi,

      Is there any way to automatically display a list of child-pages, sorted by label contents, on the parent-page?

      As far as I know the feature requested is not available yet. However, feel free to launch a feature/improvement request in JIRA:

      Hope that helps,
      Best rgds,
      Zed

  7. I've moved the specific page(s) to be children of their respective associated documents.  I want to use markup language to pick up the child pages and drop them into the right section of my page using the labels. 

    This was how I tried to do this before I realized that all of my pages are actually in the same space.  Hence the reason why they ALL show up.  IE:

    Enhancement Requests

    "contentbylabel:labels=pm-request|type=page|showLabels=false|showSpace=true|spaces=@self|sort=creation"

    Proposed Solutions

    "contentbylabel:labels=pm-sol|type=page|showLabels=false|showSpace=true|spaces=@self|sort=creation"

    Selected Solution

    "contentbylabel:labels=pm-sol-approved|type=page|showLabels=false|showSpace=false|spaces=@self|sort=creation"

    Of course, using "children:"  results in all of the children documents regardless of labels.  Any ideas?

  8. How do I specify a parent page whose title includes special characters?

    For instance, the title of the page is "Systèmes"

    I've tried {children:page=Systèmes} and {children:page=Syst&#232mes}, but neither work.

    Thanks!

    1. {children:page=Systèmes} should work.  It's possible that your instance is not configured correctly - can you try running the steps at Troubleshooting Character Encodings

      Cheers,
      Mark

  9. Is there a way to get a {blogpost} style rendering of the {children} macro? It would be nice if the excerpt of the children could be included in a more graphical way than just a line of text.

    1. Hi Vincent,
      The feature that you are after is not available, but, I agree with you that would be a nice feature to have (smile) Please feel free to create a feature request at http://jira.atlassian.com, share your comment over there, vote on it , and add yourself as a watcher for future update. Please also take note on how we implement feature request.

      Please feel free to ask again if you need further assistant.

      Thanks & regards,
      Jack

  10. Anonymous

    Hello,

    how are you displaying the page icons in the children list?

    You have it at the end of every page under Child Pages.

    Kind regards, Bernd

  11. Anonymous

    hi, what about getting the creation date to be displayed next to the children pages

  12. Is there an answer to the question how you display the page icon in front of every page as you can view it at the end of every page for child pages?

    1. Hi Udo,

      Would you be able to tell which icon are you referring to?
      As far as I am concerned, by default, there is already an icon in front of every child page.
      May I know which version of Confluence are you running? Which theme are you using?

      Cheers,
      Husein

      1. Anonymous

        Hi Husein,

        as I had the same questions a few lines up: I am running 3.2 and when I use {children}, the page icons don't show. They show, though, at the end of the page where the template includes the childpages by default

        Any way to turn that off, by the way?

        Regards,  Bernd

        1. Anonymous

          The theme is the same one used here.

  13. Anonymous

    Hi, is there any way how to show titles of children pages together with labels?

    i tried something like {children:all=true|showlabels=true} but found showlabels is not supported parameter.

    1. Anonymous

      oops... syntax works here

      the missning macro example is

  14. That doesn't work for me, what Confluence version do you use? I'm on 3.1.1 and the showlabels doesn't do anything.

  15. Including excerpts using the children macro doesn't appear to be working for me.

    The macro displays a list with 1 line per child-page.

    For each child page, it shows: the page title (hyperlinked), an mdash, and then the first line of text below the child-page's first excerpt tag.

    Not only does it only display one line of excerpt per page, but it's not even rendering tags properly.

    (I was hoping to create a rolled-up TOC showing the contents of all child pages).

    What am I doing wrong?

    1. Anonymous

      Second this problem on Confluence 3.2.1

      Also, even when it shows the one line, the line is not formatted with the wiki markup.

    2. Anonymous

      It's been nearly 3 months since this comment was posted, and 3 other people have left comments with similar issues/questions.

      Bueller? Bueller?

  16. I have an excerpt on every page, that contains a macro {term:xxx}. When using the excerpt=true, this macro is only textually rendered.

    Isnt there a way to include an option like renderexcerpt=wiki ?

    Thanks.

    michael

      1. Apparently, this was reported as a bug back in June 2008: CONF-12237and ADVMACROS-56.

        Our best bet for now may be to vote for these issues in order to raise their awareness and priority.

    1. Apparently, this was reported as a bug back in June 2008: CONF-12237and ADVMACROS-56.

      Our best bet for now may be to vote for these issues in order to raise their awareness and priority.

  17. Hi, does anyone have a way of showing the 10 most recently modified pages in a space, whether they are direct children of this page or not? I tried

    {children:sort=modified\|reverse=true\|all=true\|first=10} 
    

    but that shows the 10 children pages and all their descendants.

    Thanks!

    Emily

  18. Two comments for the authors/editors:

    A) This page should be linked to the Excerpt Macro page (among other reasons, so it will be listed in the backlinks from that page)

    B) You should clarify in the text that currently, excerpts do not support macro notation and convert macros to text (CONF-12237and ADVMACROS-56)
    As long as that's current functionality (until those bugs are fixed), this should be documented with the parameter information. One shouldn't have to discover this through trial-and-error or searching the web. It deserves more prominence than being buried within nearly 40 comments on the page.

    1. After further testing to remove macros from my glossary, I discovered that excerpt=true is even more limited - it only includes the first paragraph of the excerpt!

  19. Further testing results:

    • style= only applies to the top level of descendents

      • If all=true and you have a hierarchy of pages, grandchildren and great grandchildren will disply as an unformatted bulleted list.
    • Limitations of excerpt=true

      • Does not render macros in curly-braces, even basic text formatting like {color}
      • Does not render h1 - h6 headings
      • Only includes text until the first carraige return.
        • Not paragraph-based, because multiple lines without blank lines will only excerpt the first line
        • One bit of good news is that there doesn't appear to be a length limit, as long as the text is within a single paragraph with no carriage returns or slash-slash's.
          • I tested with the entire text of Lorem ipsum, and as long as I removed line breaks, children included the entire excerpt.
        • Further examples which only excerpt the first line:

          1. 2 paragraphs
          2. 2 lines
        • Examples which render excerpt correctly:

          1. linebreak without carriage return
          2. 2 linebreaks without carriage return

    Caveat about implementing a fix

    I've discovered all this in the process of converting a several-hundred term glossary into Confluence.

    I can probably still find a way to implement this within these limitations, but I dread the thought of having to reformat it all when you release a fix (or risking a messed-up site).

    THEREFORE as part of any modifications, you should add an additional parameter to the children macro for excerpt rendering, with these options:

    • render = false - by default continue current rendering behavior to not break current implementations
    • render = true - render the excerpt in the same rich manner as other excerpt macros, such as excerpt-include
  20. Anonymous

    Is it possible to list children in a set number of columns - i.e if there are a lot of children presenting them in three rows means less scrolling down the screen looking for a specific child.

  21. I'm not really a fan of the {pagetree} macro, therefore I use to use the {children} macro for navigation widely.

    But there is one feature of {pagetree} which I really like: It highlights (by using bold font) the page name in the branch which I'm currently visiting.

    I'd like to have the same feature for the {children} macro. Is this possible?

    (e.g. the start page of the children command is a parent or grand-parent of the current page, so I would like to see the children output with the current page highlighted)

  22. I am creating a menu of all of the pages in a Builder Theme layout. My client has changed the name of some of their home pages so when the page parameter of the children macro is set to Home I get

    I tried leaving the page parameter out but when I go to space admin I get another error. They want all of the dependencies displayed. Are there any other parameters I can use or another way around this?

  23. Hi, I've got the same problem that the anonym guy who wrote :

    "Is it possible to list children in a set number of columns - i.e if there are a lot of children presenting them in three rows means less scrolling down the screen looking for a specific child."

    Can anybody help me?

    Tks

  24. Anonymous

    Hello,

    there is this "last edited" field on every wiki page. If i have a {children}-macro on a page, the date never changes when new child-pages are appended. I understand why this is the case, but it would be nice if there is an option to change this behavior.

    Is there a workaround for this problem? This feature would be very useful for me..

    Thanks,

    Susan

  25. Anonymous

    I wanted to hide the list of child pages from displaying on a particular page. To do that, I edit the particular page and used the html macro like this:

    

    1. You can also add this line to the Global Stylesheet to hide child page lists on all pages:

      #children-section { display: none; }

  26. Anonymous

    Is there a way to not only list childpages by the last modification date but, also, to show that date near the name of the childpage? More or less like the tooltip in pagetree2 macro, but near the name as a text instead of a mouse over tooltip.

     

    Thanks in advance.

  27. Anonymous

    First of all, don't use the term to define the term.  Basically, your documentation says 'Depth of Descendants == Depth of Descendants' and 'Number of Children == Number of Children'.  Those phrases are used in the UI of confluence and I came to the documentation because I didn't fully understand what that phrase mean.  With no help from this documentation I finally figured out what the two settings mean.

    Consider these problems:

    • Descendants is a uncommon and advanced English word.  Use the term 'children' not 'descendants'.  It's more common a word and therefore easier to understand.  People come here in a confused state of mind.  Use simpler words and you'll get fewer tech support incidents and fewer rants like this one.
    • The idea that "Show Descendants" overrides other parameters is no longer in the documentation.  I can see it in older documentation but not this version.  Why did you remove that?  Did the behavior change or did the documentation simply get worse?!
    • Why did you remove the raw parameter names such as "first" or "depth".  I see them in oder documentation version, but not this one.  Again, did the documentation get worse because the information was moved somewhere else (worse documentation since I see no links to that information) or because that information gone (worse since that's useful information now missing)?!

    Consider these alternative names and definitions:

    • Show Descendants
      • Confusing because from the name alone I would interpert that to mean if the macro will display any children and then the other options to control how many at what levels.  This macro already shows children, why would you name a parmeter with a phrase that means exactly the same thing!
      • Rename to: Show all children
      • Define as: When on, shows all children of this page or the named 'Parent page'.  When on, 'Children depth' is ignored.
    • Depth of Descendants
      • Rename to: Children depth
      • Define as: The number of pages that are children of this page or the named 'Parent page' to show in the list.  If 'Show all children' is on, 'Children depth' is ignored.
    • Number of Children
      • Rename to: Direct children shown limit
        • Whatever you decide to name it, include something in the name that tells the reader it influences the first level only!
      • Define as:  The number of pages that are direct descendants of this page or the named 'Parent page' to show.  This restricts the number at the first level of child depth only.  The direct children not included in the list are the last ones.  When 'Show all children' is on, all children of this many direct descendants are shown.
    • That last sentence is a bit counter-intuitive.  I really think you should either make 'Show all children' override both of these two parameters.  Or get rid of 'Show all children' because you can figure this out with fewer arguments.  If depth = -1: show unlimited depth, if depth = undefined: show a depth of 1.
    1. Anonymous

      Hi Anonymous (wink)

      Well, myself, I'm not a native English or American, but I think I do understand some "advanced English words" .

      To me, "descendants" is not synonymous to "children", but include grandchildren, grand-grandchildren, and so on.

      Given that meaning, "descendants" does make sense to me. Some of your suggested changes are mainly due to your interpretation of "children" including grandchildrens etc. When using "children", it would be obvious to me that the show-children-limit is first level only. (because children is only one level). "Direct children" would be a tautology  (oh, that may be an uncommon word.... I mean duplicate meaning)

       

      So depending on which macro we talk about (and related functionality), I suggest to use the term "children" on macros which handle one level only, and "descendants" for macros which explode more than one level.

  28. Anonymous

    Hi all,

    is there any way to display a list of children with the headlines of that page?

    for example:

    on page2:

     

    and on the mainpage a children rendered like:

    • page1 - headline1, headline2
    • page2 - headline1
    • page3
    • ...

    ??

     

     

    1. Any update on this?  Is it possible.  This would be useful for us also.

  29. Anonymous

    is it possible to have recently updated list of descendant pages - effectively a combination of recently updated with children macro. i have tried children with sort by modified date, but that will show like tree and first level children only.

  30. Anonymous

    I need help also, but I don't know if I should open a new thread?

    I am using the “children” macro on my pages.

    I would like to combine the output of multiple children pages, such as:

    {children:page=Service Coordination\|depth=1\|style=h4}

    {children:page=Financials\|depth=1\|style=h4}

    {children:page=Asset Management\|depth=1\|style=h4}

     But I want to sort them as ALL children pages, instead of as separate sections.I am looking to merge the output and sort data.

     Is this possible?

  31. Is there a plugin or extension or other mechanism that would allow more information to be displayed about child pages?

    For example, it could be useful to display the last edit time and the last edit user along with the page name itself. The page size and number of comments (and time of last comment) could also be useful. Ideally, this feature would have a syntax for expressing the order and format of page metadata to include in each line.

    Another question is whether it is possible to combine Children Display and Table of Contents, so that headings within each selected child page could be included.

     

    1. I have used the "checklist" macro for displaying that type of content:

      {checklist}
      {checklist-wikiinput:Description|rows=3|cols=30|}\\
      
      {checklist-wiki:Date Created}{page-info:created-date|dateFormat=MM/dd/yy}
      {checklist-wiki}\\
      
      {checklist-wiki:Created By}{page-info:created-user}
      {checklist-wiki}\\
      
      {checklist-wiki:Page Contributors}{page-info:participants|type=flat}
      {checklist-wiki}\\
      
      {checklist-wiki:Comments} {link-to:page comments}Display{link-to}
      
      {checklist-wiki}\\
      
      {checklist-wiki:Attachments}{link-to:page attachments}Display{link-to}
      
      {checklist-wiki}\\
      {checklist}

       

  32. Hi,

    is there any way to display children together with the creator's profile picture?

    thanks,

    anna

  33. Is there a way to change the color of the links in child display? 

    I really want all the text to be black on the page. 

    Thanks