Breadcrumbs are a pain in the ass in Confluence. Not just because there’s a default mode where Confluence inserts an ellipses (…), but also because the default Velocity template that draws the crumbs is overly complicated.

Plus, I am getting pretty tired of adding jQuery every time I want to customize something on my site: for example, I had a line in my Custom HTML that simulates a “click” event on the ellipses just so all the crumbs would appear.

Before, my Custom HTML included the following:

<!-- Automatically expand the "..." in the breadcrumbs when the page loads -->
AJS.$('#ellipsis strong').click();
<!-- Remove the redundant breadcrumb node -->
<!-- if  there are exactly 3 breadcrumbs (for example: DevCenter > Documentation > Documentation), remove the third one (#2) to avoid redundancy -->
if (AJS.$('#breadcrumbs li').length == 3) {
  AJS.$('#breadcrumbs li').eq(2).remove();
} else {
  AJS.$('#breadcrumbs li').eq(3).remove();
}

What a PITA.

So, I decided to remove the jQuery calls, and simplify the Velocity template instead, customizing the crumbs to meet my site’s needs. Here’s my commented version of the breadcrumbs.vm file. This file is located in the /confluence directory.

Note: The file looks long, but half the lines are comments:

#requireResource("confluence.web.resources:breadcrumbs")
## breadcrumbs is a List of AbstractBreadcrumb objects
## http://docs.atlassian.com/atlassian-confluence/latest/com/atlassian/confluence/util/breadcrumbs/AbstractBreadcrumb.html
#set ($breadcrumbs = $helper.breadcrumbs)
<content tag="breadcrumbs">
  #set ($counter = 0)
  <ol id="breadcrumbs">
    ## iterate over each breadcrumb
    #foreach( $breadcrumb in $breadcrumbs )
      ## skip the first two breadcrumbs (0 and 1) because they are redundant and unnecessary
      #if ($counter > 1)
        ## if it's the second breadcrumb, then set the LI class to "first" so Confluence does not draw the separator
        #if ($counter == 2) #set($crumbString = "first") #else #set($crumbString = "") #end

        ## get the displayTitle property to set the text of the crumb
        #set ($displayTitle = $breadcrumb.displayTitle)

        ## draw the breadcrumb with the contentPath and target as the link, displayTitle as the text
        <li class="$crumbString"><span><a href="$req.contextPath$breadcrumb.target">$displayTitle</a></span></li>
      #else
        ## do nothing
      #end ## end counter > 1
      ## increment the counter
      #set($counter = $counter + 1)
    #end ## end foreach
  </ol>
</content>

Yeah, yeah, I know. It will break when I upgrade. It lacks much error checking. It doesn’t support tooltips. Whatever, it suits my needs.

To customize the separator, I just replace the images/decoration/white_breadcrumbs_indicator.png to an image that I want. I didn’t bother trying to track down where that image is set (I’m almost certain it’s hardcoded in the WAR file somewhere, and I just don’t have the heart to find it).

Overview

Recently, we had a requirement to add several sets of API documentation to our Confluence website. While the API docs are static, they have some funky characteristics that make them difficult to include in Confluence:

• Source is generated from multiple tools — Our API docs will be generated form Doxygen and JSDoc. Neither of these can be imported as Confluence pages
• Source is generated at regular intervals — As the APIs change, so will the docs. As a result, adding the API docs to Confluence would not be a one-time event. It would have to happen every time the API changes.
• Source docs should be developer friendly — The format for API docs used by Doxygen and JSDoc are known and loved by developers. We don’t want the Confluence styles to be applied to these docs.

Because of these reasons, we decided to add the API docs as static HTML in their own subdirectories of our Confluence-based documentation. Basically, we want users to be able to navigate to them, but NOT view them within Confluence.

However, we also wanted to use the existing Confluence/Crowd authentication scheme on these docs. If a user navigates to the API docs, we wanted them to first have to log in, just as they would if they navigated to the Confluence-based technical documentation.

Set up

Seraph-based authentication ties into Crowd’s groups. You can identify a group that has rights to access assets that match any path.

This technique piggybacks on the Seraph HTTP authentication scheme. This scheme is used to protect the “admin” application in Confluence. However, it can be expanded to include any number of arbitrary directories within the Confluence installation.

Copy HTML files to Confluence

Copy the HTML files to the confluence/confluence directory. These files should be at the same level as the static resources such as the “admin” and “images” directories.

Add a new path and role

To add a new path under Seraph, edit the seraph-paths.xml file. This file is located in confluence/WEB-INF/classes. Add a new path and define its URL pattern and role-name.

The following example adds the path /api-docs and indicates that only members of the “customers” group can access resources in that directory:

<security-paths>
    <path name="adminJspPath">
        <url-pattern>/admin/*.jsp</url-pattern>
        <role-name>admin_jsp_role</role-name>
    </path>
    <path name="admin">
        <url-pattern>/admin/*</url-pattern>
        <role-name>confluenceadmin_seraph_role</role-name>
    </path>
    <!-- Add new path/role: -->
    <path name="api-docs">
        <url-pattern>/api-docs/*</url-pattern>
        <role-name>customers</role-name>
    </path>
</security-paths>

Apply no decorator by default

By default, Confluence will attempt to apply its decorators to assets protected by Seraph. To avoid this, edit the decorators.xml file. Within the <decorator name="none"> block, add the following:

<url-pattern>/api-docs/*</url-pattern>

This tells Confluence to apply no decorator to any file served up under this path.

Issues/Risks

1. Seraph only appears to support giving one Crowd group access permissions to the path, despite Atlassian documentation to the contrary.
2. Upgrading to a new version of the server will require re-adding the paths, roles, and decorator rules. If the new version of Confluence changes syntax or no longer supports Seraph, then this technique may no longer work.
3. Based on the lack of documentation, I suspect this “feature” is unsupported by Atlassian. Use at your own risk.

Resources

The following resources came in handy when trying to understand how to use static HTML in a Crowd/Confluence setup:

• Atlassian Seraph documentation: http://docs.atlassian.com/atlassian-seraph/latest/services.html
• Basic info about Seraph in Confluence: https://developer.atlassian.com/display/CONFDEV/HTTP+authentication+with+Seraph
• Bug filed regarding the single group support: https://support.atlassian.com/browse/CSP-93517