Blog Archives

New style for Confluence documentation – what do you think

To mark the impending release of Confluence 5.0, we’ve applied a new style to the Confluence documentation. It’s done by means of some snazzy CSS, created by Andrew Prentice, Valter Fatia and Paul Watson.

What do you think of the new look? We’d love your feedback on the styles, the way some information is hidden until you hover over it (try zooming your cursor around the page to find the hidden bits) and the contrast with the standard Confluence 5.0 look.

Our customised styles

We’ve applied custom CSS only to the latest documentation space on the wiki – that’s the documentation for Confluence 5.0. This space is using the Documentation theme, but with a lot of CSS on top:

Documentation space with custom stylesheets

Documentation space with custom stylesheets

The standard Confluence 5.0 styles in the Documentation theme

The documentation for Confluence 4.3 is on the same wiki, but we haven’t applied the custom stylesheets. The wiki is already running Confluence 5.0, so you can see the new 5.0 look and feel without any custom styling. The space is using the Documentation theme:

Documentation space with standard styling

Documentation space with standard styling

The standard Confluence 5.0 styles in the default theme

Just for completeness, here’s the Atlassian Training space, on the same wiki, but using the default Confluence 5.0 theme:

A space using the default Confluence 5.0 theme

A space using the default Confluence 5.0 theme

How do you add CSS to a Confluence space?

It’s all in the documentation: Styling Confluence with CSS.

Thoughts? 🙂

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! 😉

%d bloggers like this: