Creating a custom breadcrumb trail using Reporting

[#1]

One nice thing about being a Confluence wiki space admin is the ability to build in tweaks and tools that make it easier to administer a space. As a technical writer and space admin, I copied and pasted wiki page links into email about a bazillion times a day. I wanted my copy-able page links to work a certain way.

Fortunately, I was able to use ServiceRocket's Reporting add-on to add a customized breadcrumb trail to the bottom of every page that works exactly how I want.

While creating a "stale pages" report for another team, I discovered I could show the page's full path (page:ancestors) instead of just the parent page (page:parent). (This made it easier for the team's space admin to sort by section and update adjacent pages at the same time.) I adjusted the Separator parameter to " > " .  Here’s how it looked in a demo space.

"That looks just like a breadcrumb trail," I thought. "How can I use this?"

I realized Confluence's default breadcrumbs at the top of each page are fine for navigating. But I needed breadcrumbs that were better for sharing. I had already added a "You are here" link in the space’s page footer that used the Adaptavist Page info macro, information type = Tiny url, like so.  decided to improve its utility by adding the breadcrumb path to it. 

First pass 

On a new page, I worked out my breadcrumb design. I tested several add-ons and macros to see what page information could be displayed. The final design used, in order,

• a Report Info macro (key = page:ancestors, separator = “ > “  and “link to item” is checked)

• a space and another >
• the Adaptavist Page info macro to display the current page name linked with the tinyurl. (I used the tinyurl since I often emailed links to draft pages, whose titles would sometimes change.)

One UX recommendation for breadcrumbs is to not make the current page title clickable. Why tempt the user to click through to the page they're already on? For my use case (sharing), I did want it clickable. For a different use case (navigation) I probably would not make it clickable. 

Second pass  

I tested out my new "You are here" breadcrumb trail on pages both higher and lower in the page tree. Long trails made it hard to see the crumbs. I used a triangle symbol to make it more obvious, and changed the color of the last one as a visual aid to finding the last entry in the path.

Implementation 

Next I used the Wikifier RT website to generate the wiki markup for the space footer.

Example using Page info macro

{report-info:page:ancestors|link=true|separator=" ► "} {color:orange}►{color} {page-info:tinyurl|page=@self}

Example using Report Info macro

{report-info:page:ancestors|link=true|separator=" ► "} {color:orange}►{color} {report-info:page:title|link=true}

Then I plugged my new breadcrumb trail markup into the space's page footer. I already had some footer elements in there, so I added a \\ in the markup to put the breadcrumbs and the help links on different lines.

You are here: {report-info:page:ancestors|link=true|separator=" ► "} {color:orange}►{color} {page-info:tinyurl|page=@self} \\ [Search tips|http://www.google.com] • [Feedback|mailto:null@null.com] • [Help|http://www.google.com]

And it looked like this:

Results

The custom breadcrumb trail using the tinyurl is an unobtrusive and useful enhancement for me as a space admin and for knowledgeable users. I can copy just the page name or the whole path and paste it into an email.

I’m trying to coach my users into doing the same, but pasting long ugly URLs from the browser’s address bar is an old habit that dies hard.

The custom breadcrumb trail complements but doesn't replace the default Confluence breadcrumbs. It could be used in a template, on an individual page, in a space header or footer, or wherever it’s most useful. If you decide to use it I would love to see your implementation.