Nested expand macros in Confluence wiki

This week I discovered that you can embed one {expand} macro inside another, to create a tree of expandable sections on a Confluence page. This is useful for a new navigation panel that we’re designing, and it’s probably useful in other situations too.

TL;DR: Add a number of expand macros. For example, {expand}, {expand2} and {expand3}. The code for each one is identical to the code for the original {expand} macro. (See the docs.) Nest away!

The details

We’ve been using the {expand} macro for a while. It defines an expandable section (a show/hide panel) on a Confluence page. Up to now, we have only ever needed a single layer of expandable sections.

First, the basic {expand} macro

The {expand} macro defines an expandable section on a Confluence page, and indicates it with a blue arrow as shown in the first screenshot below.

An expandable section, collapsed

Here is the page after someone has clicked the text next to the blue arrow:

An expandable section, expanded

The {expand} macro is not shipped with Confluence, or not yet. I’m using Confluence 3.5. The macro will be part of Confluence 4.0, due for release soon.

The {expand} macro is a user macro. That means that you can add it to Confluence quite easily, by entering some code into a form on the Confluence administration console. You do need to be a Confluence system administrator. The Confluence documentation describes how to add the macro.

Once you have added the macro, people can use it on their wiki pages. The basic format is this:

{expand:title=Click here to show text...}
All this text is hidden inside a show/hide block.
{expand}

So far, so good. Where does the nesting come into it?

Nesting the expandable sections

This week I came across a situation where it would be nice to embed one expandable section inside another. To show you what I mean, I’ve made up a dummy page with three nested layers of expandable sections. In this screenshot, just the first level (“Fruit and veg”) is expanded:

Just the top level expanded

In the next screenshot, the “Fruit” level is expanded too:

Two levels expanded

And here’s the page with all levels expanded:

All levels expanded

Each of the blue arrows is produced by an expand macro. Inside the third layer, I have used a bulleted list to display the lowest level of categorisation. For example, the bulleted list shows the types of apple: “Granny Smith”, “Golden Delicious”  and “Red Delicious”.

How to nest the {expand} macros

First you need to add a few more user macros, one for each layer in your nested tree. For my example I needed three layers.

• The original {expand} macro supplies the “Fruit and veg” layer.
• I added an {expand2} macro for the “Fruit” layer and the “Vegetables” layer.
• I added an {expand3} macro for the types of fruit (“Apples” and “Oranges”) and the types of vegetable (“Potatoes” and “Carrots”).

The code for the {expand2} and {expand3} macros is exactly the same as the code for the original {expand} macro.  The Confluence documentation describes how to add the {expand} macro and gives the full code.

Next, use the three macros on a Confluence page. Here is the full wiki markup of my example page:

{expand:title=Fruit and veg}

{expand2:title=Fruit}

{expand3:title=Apples}
* Granny Smith
* Golden Delicious
* Red Delicious
{expand3}

{expand3:title=Oranges}
* Navel
* Valencia
{expand3}

{expand2}

{expand2:title=Vegetables}

{expand3:title=Potatoes}
* Marfona
* Nicola
* King Edward
{expand3}

{expand3:title=Carrots}
* Nantes
* Chantenay
{expand3}

{expand2}
{expand}

That’s it! 🙂