Question for Ecosystem Partners from Atlassian / Confluence Cloud regarding html "Heading" tags

Hi All,

We’ve noticed a bug in our current Table of Contents macro, that we want to fix. But it might affect partners, so we have a couple questions to get started:

  1. Does anyone use < h1 > through < h6 > html heading tags in their extension?
  2. Do you count on these appearing within our Table of Contents macro?

The plan is to start explicitly excluding these from our TOC, as this was unintentionally done AND is flaky behavior currently due to race conditions. Please let us know as soon as you can, we plan on fixing this bug ASAP.

1 Like

For clarification: would this only change which headings would be output by the TOC macro or would it also change the HTML structure that the TOC macro outputs?

Background: in some of our apps we parse the HTML output of the macro so we can process some of the links in there, which would need adapting if the structure changes. If the only thing changing is which headings are collected in the macro, we wouldn’t be affected.

@thomas2 thats a great question - the intention is to only affect what headings are pulled in by the TOC, but I will have to double check with the devs on whether the TOC rendered structure is exactly the same or not - the intention is for it to look exactly the same to the user, but of course structurally it might be different.

Can you tell us what HTML structures you’re looking at within the TOC and I can double check with my dev? I’d have to assume worst case we can’t make it match but you’ll still be able to adapt to the new one.

@DennisLu we’re pretty much just looking for links to headings inside the toc-macro container, so everything found by this selector: .toc-macro a[href]. For the parsing it sounds like we probably won’t have to adapt anything.
We do transform these links and then rebuild the ToC structure ourself with the transformed links though, so if the structure changes we might need to adapt so that our code rebuilds the same structure.

So glad you asked!

This could plausibly affect users of ScriptRunner for Confluence’s Markdown Macro. It just renders Markdown into HTML as you’d expect. Right now, the Table of Contents macro does include headings from the Markdown.

That said, we don’t advertise or rely on that behavior for the macro’s main functionality. We can’t say for certain that we don’t have customers who are relying on it, but it seems unlikely.


It would not affect Content Formatting for Confluence if you made this change.


The dev came back and said that this should still work - it looks like the structure in the new version is exactly the same. Of course I’ll come back here and mention when we’ve done the preliminary release to the ecosystem testing group so you can double check.

@jcarter That’s an interesting situation - as you said hopefully not many customers are affected by our coming change then. After we make the change please do let us know if any feedback comes back to you about it.

1 Like