Space jumping in a wiki documentation theme

A couple of weeks ago, I wrote about the new Documentation theme for Confluence wiki. There’s a bit I didn’t write about — something we technical writers requested specifically. It’s called “space jumping” and it’s just as awesome as its namesake.πŸ˜‰

It’s a cold and wet Christmas long weekend, so I’ve decided to write a blog post about wikis instead of venturing outside:

Space jumping in a wiki documentation theme

Space jumping lets you link from a page in one wiki space to a page with the same name in another space, without knowing the name of the page when you create the link. It’s done via the {spacejump} macro that is part of the new Documentation theme.

Why would you need to space jump?

Apart from the sheer thrill of it, you mean?πŸ˜‰

We use it to put a standard message at the top of our archive spaces, telling people that they’re reading an old version of the documentation and letting them jump quickly to the same page in the latest documentation.

The result looks like this:

Space jumping in wiki documentation theme

Here it is again, in text instead of an image:

This documentation relates to an earlier version of Crowd.
View this page in the current documentation or visit the current documentation home.

And here’s the full screen (click the image to expand it):

Space jumping in wiki documentation theme

If someone clicks the link on “View this page in the current documentation”, they are taken to the latest version of the page:

Space jumping in wiki documentation theme

Here’s a link to the archive page in our documentation, so you can see the space jump in action.

How did we do that?

We’ve put the {spacejump} macro into the theme configuration. Here’s what our wiki markup looks like:

{note:icon=false}*This documentation relates to an earlier version of Crowd.*
View {spacejump:CROWD|alias=this page in the current documentation} or visit the [current documentation home|CROWD:].{note}

The format of the macro is:

{spacejump:SPACEKEY|alias=TEXT}

The ‘SPACEKEY’ parameter is required. Replace ‘SPACEKEY’ with the key of the space you want to jump to.

The ‘alias=TEXT’ parameter is optional. If you use it, replace ‘TEXT’ with the text you want hyperlinked. If you omit the parameter, Confluence will display the page name.

The macro is part of the Documentation theme, so if you have installed the theme then you can use the macro. We’ve used it in the theme configuration, but you can also use the macro on a normal wiki page.

Here’s a screenshot showing our full theme configuration for the archive space (click the image to expand it):

Space jumping in wiki documentation theme

What happens if the page does not exist in the target space?

For the space jump to work, the target space must contain a page with the same name as the page that renders the {spacejump} macro. If the target space does not contain such a page, you will see a broken link. Confluence handles this in its usual manner: the link is coloured red, and if you click it then Confluence offers to create the page for you.

In our particular use case a missing page is not very likely, because we seldom delete pages and our link points to the latest documentation space.

There’s probably a better way of handling unmatched pages. Maybe this is a chance for someone to raise an improvement request in the issue tracker for Jens’s Documentation theme!πŸ˜‰

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 28 December 2009, in atlassian, Confluence, technical writing and tagged , , , , , , , , , , , . Bookmark the permalink. 6 Comments.

  1. Awesome – Thanks for the tip!

  2. Hi Sarah!

    Is this still the plug-in you use in the Confluence docs? Viewing a page’s wiki markup (this page, for example: http://confluence.atlassian.com/display/CONF33/Confluence+Documentation+Home) didn’t reveal this macro syntax at the top of the page.

    • Hallo MichaelπŸ™‚
      Yes, we still use the plugin. The markup won’t show in the page’s wiki markup, because it’s in the header portion of the Documentation theme configuration. To add it to your own space, go to Browse > Space Admin > Themes > Configure theme. (Assuming you have chosen the Documentation theme as the theme for your space.)

  3. …And you actually describe exactly how it is used in your blog article. Don’t know how I missed it! Mea culpa!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: