Another working week has flown by and sadly it was a forum-free week: my time was devoted to more urgent tasks, such as writing a How-To guide on setting up and using blogs.

Not that I mind giving people more info on how to make better use of Confluence, but sometimes when you really want to crack on with a project, it becomes a project that is destined to slip out your grasp. 

Ultimately that won't happen with the forum, because I'm determined not to let go of it until it's working and being used by clients.

Shortcuts and Macros
One of the jobs I've been doing as a background task for the last few weeks has been to convert the contents of a spreadsheet into a series of wiki pages.

This equates to seven columns of data for each row, and several hundred rows, all of which have to be split into separate pages. Each page contains one or more table depending on the type of info. And while all of these are separate pages (99 in total), they all have to be grouped into one page so that they can be searched en-masse and printed as a PDF.

The process for doing this is easier than you think, thanks to some helpful built-in functionality, aka, macros.

Although adding all the data from the spreadsheet is laborious and time-consuming, once you've added them, the process of grouping them onto one page is very easy. All you have to do is insert a macro into the page you've created to group the content on, choose the page you want to include, then saving the macro and the page. The whole process takes about a minute normally.

To do this you can use another one of Confluence's brilliant shortcuts. In this case the shortcut is the left facing curly bracket. 

Another example of a shortcut is pressing the 'E' key to open the current page in edit mode. Brilliant! It's this sort of thing turns Confluence into the Swiss Army Knife of technical documentation.

When you're in Edit mode, enter a '{' and the Macro suggestions window opens, see Figure 1Next press the Up arrow key to select the Open Macro Browser option, and press Return.

Now start typing the letters 'I, N, C' (you can use lower case, these are capitalised for clarity) in the search box. Bear in mind that you don't even have to click in the search box as the cursor's already there 
(yep, even more labour saved). 

When you do this, the number of macros displayed is reduced to only those whose name contains the letters you enter.

The next step is to select the appropriate macro and enter the only parameter it needs, the page's name. 

Figure 2 shows the Include Page macro, while Figure 3 shows the parameter I've entered in the Page to include field. All you have to do now is press Insert to close the macro window, and then save the page.

When you do this, the macro automatically gets the content of the parameter page and displays it on the page you've just saved. To add all the other pages you need using a seperate Include Page macro for each one.

The contents of the group page are automatically refreshed whenever you open it, so if the content of the parameter page is edited, it is the new content that is displayed.

But wait, I hear you say, what if I want to include a page that is in another space, is that possible? Providing you have permission to view that page, then yes it is possible - and not only that, Confluence makes it easy for you to do so. 

Spaced In
When you start typing in the Page to include field, after you've entered two or more letters a list appears based on those letters, see Figure 4.

The list contains pages with that name from all the spaces you can see. If you run the mouse over the options, the name of the space appears, see Figure 5.

All you have to do is select the appropriate option, press Insert and save the page. The parameter you select has both the space's key and the page's name, for example - spacekey:pagename.

I'm not sure if there's a limit on the amount of Include Page macros you can use on one page, but I've used 67 so far one page and it still works exactly as expected. In most cases you won't need to use so many (and if you do stand by for some te-di-um) and the benefits are well worth the effort. 

For a start you'll have all the info in one place, which makes it very easy to create a PDF (in two clicks) with all the content from all the included pages. For searching, you'll have all individual pages which can all appear as separate results. And you'll have one page with all the appropriate info which you can search using your browser's built in functionality.

Details and Benefits
What I like about the ease of use we get with the shortcuts and macros is the attention to detail they show. Both demonstrate how much thought Atlassian put into their products, thought that all Confluence users can benefit from.
4/1/2012 05:41:57 am

Nice post.

Not sure if you were aware, but you can save yourself a couple of clicks by typing the name of the macro after the "{", e.g.:


this will narrow down the initial pop-up and take you straight to the entry for the Include Page macro (Figure 3) rather than you having to search for it in the Macro Browser.

If you're on 4.1.2 + you can also enter the entire thing in the editor without having to use the mouse at all, e.g.

{include:Name of Page to Include}

you don't get auto-complete for the page name, but if you know what the name is it's even quicker than using the Macro Browser.

4/1/2012 06:54:45 am

Hallo Mick

Nice post. I love the amount of detail you've put into it.

On the point about permissions, when you include a page from another space: It's worth mentioning that the permissions of the person viewing the page count too. If the reader does not have permission to see the content of the page in the other space, they will not see the content when it's included on your page.


4/1/2012 08:09:56 am

Thanks, I intend to do more like this, hopefully with video too.

You make a good point about permissions, I was thinking about it from the point of view of the person creating the page AND that the info was basically the same (but different). But of course, other people might not have permission to view some of the content, so won't see it.

I was discussing just this with a colleague last week. We've got to put together some user info that will be for several clients who use the software in different ways. We have to make sure that each client does not see the client-specific info of the others. Through writing this and getting your input, I can visualise exactly how that will work. Thanks! :)

How's the IRKD app going? :)

4/1/2012 08:03:30 am

now that is great isn't it? :) I had no idea you could do that, and I've just tested it, so I know it works. Excellent, thanks. As usual with Confluence, expect the unexpected. :)


Leave a Reply.