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

Question

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.

Kim Melançon · Answer

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).

Rob Woodgate · Answer

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.

Milo Test · Answer

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.