Macro heading links in TOC are wrong

Hi! Our app has a static content macro which displays arbitrary content, including headings. These are returned as storage format in the body of the response for our macro. We recently received support which showed that the headings inside the macro do not work well with Atlassian’s TOC element.

Normally a heading in a TOC will link to the element id of the heading on the page, e.g. #Lorem. However, when concerning a heading inside our macro, the link in the TOC and the id do not match. The TOC will still link to #Lorem, but the id of the heading in the macro will be PageName-Lorem, where ‘PageName’ is a version of the name of the page. This means the link does not work.

This id of the heading element in the macro is set by Confluence (in fact any id that we set in our response is removed), so we’re not sure at this point how to get the TOC and macro heading links to work correctly together.

It is of note that Atlassian’s Excerpt macro does not show this problem. Headings inside this macro get a normal id and the TOC link works as expected. Investigating the storage format and ADF sources of our macro and the Excerpt macro, we could not find any differences in the definition of the macro or its content that would explain the behavior.

Is it possible for headings in the body of our macro to have correct ids that correspond to those in the TOC? How can we do it? Or is this a bug or missing feature in Confluence? Thanks!

This problem is still present. To further clarify my original post, here is a step-by-step for reproducing the problem.

  • Create a page, e.g called “Test Page”
  • On the page, add the following:
    • Table of Content macro
    • Heading 1 with text “Heading outside macro”
    • Custom Static Content Macro with the below content which is displayed verbatim:
      • Heading 1 with text “Heading inside macro”
  • Save the page and go to the page view:


  • Inspecting the page view HTML source, we find something like this (simplified):
<div title="Macro (toc)">
    <a href="#Heading-outside-macro">Heading outside macro</span>
    <a href="#Heading-inside-macro">Heading inside macro</span>
<h1 id="Heading-outside-macro">Heading outside macro</h1>
<div title="Macro (custom)">
    <h1 id="TestPage-Headinginsidemacro">Heading inside macro</h1>
  • Examining the TOC link for “Heading outside macro”, we see it links to the anchor #Heading-outside-macro. This corresponds to the id for that heading.
  • Examining the TOC link for “Heading inside macro” we see it links to the anchor #Heading-inside-macro. This does not correspond to the id for that heading, which is actually TestPage-Headinginsidemacro (containing the page name and the heading text)

There seems to be a different logic for generating the id of headings outside and inside a macro. Because of this, clicking the link in the TOC which refers to a heading inside a macro, does not do anything.

To fix this, either the TOC has to match (for links inside macros) the id generation logic used inside macros, or the macro has to use the same id generation logic as is used outside of macros.

I’m very interested in hearing about alternative solutions that we can implement on our end. But it seems this is a problem with Confluence. Thanks in advance!