Duplicate heading anchors in Confluence

There's a bug in Confluence 4.2 that generates identical IDs for same-name heading elements (CONF-17962). The issue is fixed in Confluence 4.3 but here is a workaround for those stuck with Confluence 4.2 or earlier.

Multiple same-name headings on the same page are OK. In fact, they are quite common. When I document objects that have similar properties I need to repeat headings. The problem in Confluence 4.2 is that you can't link to such headings (anchors). The link always points to the first occurrence of the heading.

Example: I use the following heading structure in message types documentation:
  • Banners
    • Behavior
    • Levels
    • Examples
    • Looks like
    • How to show
  • Alerts
    • Behavior
    • Levels
    • Examples
    • Looks like
    • How to show
  • Notifications
    • Behavior
    • Levels
    • Examples
    • Looks like
    • How to show

Confluence generates IDs using a pattern where page title and heading are concatenated with a hyphen in between:
<page title>-<heading name>

As a result, the IDs of all my "Behavior" headings are identical:
<h3 id="Messagestypes-Behavior">Behavior</h3>
<h3 id="Messagestypes-Behavior">Behavior</h3>
<h3 id="Messagestypes-Behavior">Behavior</h3>

Workaround. Add the Anchor macro in front of the lower level heading. Set the anchor name to the upper level heading followed by a hyphen.


This creates unique IDs:
<h3 id="Messagestypes-Banners-Behavior">Behavior</h3>
<h3 id="Messagestypes-Alerts-Behavior">Behavior</h3>
<h3 id="Messagestypes-Notifications-Behavior">Behavior</h3>