How to show Child Pages when using the Include Page macro?

We are setting up an Inclusion Library so that we can re-use content across several User Guides.

The issue we are facing is that when the Child Pages macro is in the content of the page in the Inclusion Library (the included page), it displays only the pages that are children of the Included Page, not the local page.

Right now we have several Spaces: _Library (the inclusion library), Website Guide, Data Management Guide, etc.  The same page from the _Library will be included in the Guides, but when we do that, the Child Pages macros displays the children of the page in the _Library space, not of the space where the page is Included into.

We need the Child Pages macro to display the children of the page in the local Guide, not of the Inclusion Library.

4 answers

1 vote

That's not going to happen with that macro.  The point of the child macro is that it shows child pages of the page it is used on.  It doesn't make sense to have it display other pages depending on how you happen to be viewing a page (why should I get one set of pages listed that are children of it when I go to "my page", but a totally different list if I go to "everyone's page which includes 'my page'"?).  I can sort of see uses for it, but in the vast majority of use cases, no.  You want the child macro to genuinely show the children of that page.

I suspect you'll need to write your own macro for this, and I think it's going to need to be an add-on, not a user macro.

Why don't you just add the Child Pages macro to the target pages and remove it from the source pages? If the source pages are also used by themselves, then add the Except macro, and put all the text except the Child Pages macro in the Except macro, then use the Include Except in the target pages.

Hi Richard,

+1 for Nic's explanation and Milo's workaround.

If you want to single source your documentation then you need to use Excerpt and Excerpt Include macros (it sounds like you're a technical writer-type person, so if it helps think of these like snippets in MadCap Flare).  

You can single source entire static pages and single source some pages that have dynamic content using the Include Page macro.  You can only use this for pages with dynamic macros if those macros don't rely on the location of the page for their data. 

So, as you've discovered, a Child Pages macro as you're using it relies on the page it's on, so when you use the Include Page macro - which just displays a faithful recreation of the page you want to include - it'll show the content of the Child Pages macro exactly as it's rendered in the original page.

If you were to have a JIRA Issues macro that showed you e.g. "all issues with a status of In Progress from a particular project" then that would work fine within an Include Page macro because the content of the JIRA Issues macro will be the same everywhere (assuming permissions are the same).

Confluence has some single sourcing capability, but it is absolutely not a Help Authoring Tool like Flare, RoboHelp, etc. It helps if you understand that and are prepared to accept some reduced functionality from the start.

There are however some useful add-ons, like Include Content By Label and Glossary which might help you produce your documentation.  You might also find the Scroll suite of add-ons useful.

The Inclusion Library consists of your reusable topics. 

Typically you would create a wrapper topic in each of your books and use the include macro to add the reusable topic to the wrapper topic. Then, in the wrapper topic, you would add the Child Pages macro below the Include Page macro.  This way, the Child Pages macro will list the subordinate pages of where the wrapper topic is located (as opposed to the subordinate topics in the Include Library).


Suggest an answer

Log in or Sign up to answer
Community showcase
Posted Feb 06, 2019 in Confluence

Try out the new editing experience

Hi team, I’m Avinoam, a product manager on Confluence Cloud, and today I’m really excited to let the Community know that all customers can now try out the new editing experience and see some of the ...

1,028 views 51 8
Join discussion

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you