It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

A better way to create product documenation, with labels, {multi-Excerpt} and {hide-if} macros


We want to use Confluence to build an installation manual for our products…

We have developed an approach that I will describe later on. My basic question is: is this a good way to approach the problem, is there a better way. Are there any pitfalls that I’m not seeing?

The problem we have is: We have many versions of the same product. Each version has updates. Therefore many sections will be repeated over and over. We intend to dedicate a different space for each version of the product.

So in each space we create, or copy, many boilerplate sections that are common to every product we sell, for example the System Requirements section.

In Confluence, using macros, we can create a master page and then include the sections that we need using these macros {include} {excerpt} or {multi-Excerpt}..

But each version of our product has slightly different requirements.

We are able to manage this by using the {show-if:label=xxx} macro to add in extra information that might be part of this release or version but not others.

So, here's an example:

If a new product runs on Windows we add label=windows, if it runs on Mac we add label=mac. Note: the label needs to be added at the level where the content was created, not at the level where it was included.

So basically this is how it might look:

Page: SystemRequirments


Common Requirements for all systems

Requirements for Windows based system


Requirements for Macintosh based system


More Common Requirements for all systems

To include this in a page we say




Information specific to this release.



We could use {mutli-excerpt} name capability to split a page into different sections.

But how to manage this:

Let’s say we come up with a new product. We take our existing space and copy it to a new space. This copys all the page, with their labels.

This gives us the basic structure and all of the boilerplate blocks including our System Requirements page.

These are the issues:

-Since the labels are evaluated at the level of where the pages are written and not where their used, you have to copy all of the boilerplate pages into a new space for this section of the documentation.

- We now need to visit each one of the Boilerplate pages to update the labels.

- It appears that we can support nested pages using the {multi-excerpt} macro

- It appears that we can pull these pages from other spaces. But this is of no use since the labels need to be at the level the page was created and therefore pages from other spaces can’t be reused.

- We found a macro that would allow us to manage labels “Confluence label Management plugin” but it does not run with current versions of confluence.

So that’s it. If anyone has any better ideas, please let us know.

5 answers

I guess since noone has commented on this, its not a popular way to do things??

Ok, I'll bite on this one even though I don't necessarily have better ideas (yet).

Can you tell us how much content you expect to have. Are you wishing to assemble just one page for each product, which is built of the include/excerpts or more than one?

Is there a reason not to just control the content on the home page (or how ever many you answer for the last question) instead of including from other pages?

Maybe you would spell out the structure a bit more..., i.e.

Home Page contains:


Sys Requirements


Other page...

To help you think outside the box, I would suggest this page and this one.

Manual will be 50-70 pages long. We will have 3 variations to start.

My guess is that it there will be the normal hiearchy of pages and that the, License and system requirments will be on this first page. But there might other boilerplate section to be incldued. I could see some tutorial sections in common between each product variation.

Just so you know, i have a software development background, so i approach all problems as thought its a program, so this might be overkill.

But I've also used systems like RoboHelp and have found that you always want to do things like i've described, or you will have to spend hours updatding each release..

I get the impression that the number of boilerplate pages is less than 50. I would suggest that you create the boilerplate pages so they each contain all the variable content they might need. Just embed it right on that page. Then use the {show-if} along with lablels on just those pages to control what shows. This will make it easy to copy the content and then you can just toggle the labels as needed. You might attach a label "boilerplate" to those pages. Then you can search on that when you fork a new space and make your checklist of pages to visit. Ctrl-MB1 to open each in a new tab and you are done in a flash.

Suggest an answer

Log in or Sign up to answer
Community showcase
Published in Confluence

How To: get the most out of the new Confluence navigation and Home

Hi Community, Elaine again from Confluence Cloud Product Management. Most of you have used the new Confluence navigation and Home for some time by now. Not sure what changed or just want to lear...

480 views 3 10
Read article

Community Events

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

Find an event

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

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you