Numbered Headings in Confluence: Why It's Harder Than It Looks (and how we approached it)

[#1]

For more than twenty years, Confluence has helped teams create structured documentation, yet one deceptively simple thing has stayed hard to solve properly: numbered headings.

It's not a new ask.
"Numbered Headings" has been one of the longest-standing Confluence feature requests (this one, to be fully exact), especially for teams working on specifications, legal documents, procedures, and audits - basically anywhere section numbers aren't optional. Atlassian itself has acknowledged that "many teams require numbered headings for many cases ranging from specifications to the legal profession."

So why is it still a gap?
Because it's harder than it looks.

Confluence stores headings as semantic elements: H1, H2, H3, and so on. Those describe structure, but they don't carry an actual "section number." To number them correctly, a solution has to read the whole page, understand the heading hierarchy, track counters across multiple levels, handle skipped or missing levels, apply the right format, and then update everything again when the document changes. The hard part isn't adding the numbers once - it's keeping them correct.

That's the problem we set out to handle. But we did it with a rather different approach. Instead of caring for one feature and shipping it as a single solution, we added the number headings as a feature of our existing solution Macro Pack. Now users can not only benefit from 20+ Confluence macros, from simple file embeds to Mermaid diagrams and code, but also experience cleaner handling when applying, updating, and removing numbering prefixes in their Confluence headings.

What this feature does, briefly. It applies (or removes) a consistent numbering prefix to every heading on a page.

Overview / Goals / Background

becomes

1. Overview / 2. Goals / 3. Background

with sub-headings following as 2.1 Scope, 2.1.1 Requirements, and so on. Re-running it re-numbers cleanly instead of stacking stale prefixes.

A few things that mattered to us when building this feature out:

• Predefined schemes for the conventions people actually use: ISO 2145 (1, 1.1, 1.1.1), compound/local decimal, outline (I., I.A., I.A.1.), alphanumeric, and lower/upper Latin, Roman, and Greek

• A custom syntax for house styles, using tags like {L1.upper-roman} and {br} to build prefixes such as Part I → Chapter 1

• Per-level start numbers (begin at 3. mid-sequence, or 0 for an appendix)

• Skip-heading controls, so you can leave an H1 title un-numbered and start numbering at H2

• Import / Export of the configuration as JSON, so a numbering convention can be shared across pages and teammates

Why does numbering matter at all?
It's easy to write this off as cosmetic. It isn't. Numbers make cross-references possible; like"see section 4.2" only works if there is a 4.2. They encode hierarchy at a glance, which is exactly why ISO 2145 exists: numbering "clarifies the sequence, importance and interrelation" of sections and "makes possible the citation of single parts of the text." And in regulated or technical work, SOPs, quality manuals, validation protocols, RFPs, contracts, numbered sections are often simply required.

Numbered Headings is one piece of Macro Pack (20+ macros for richer Confluence documentation), but it fits the same goal: helping teams standardize structure, cut manual formatting, and make important pages easier to navigate and trust.

If you want to try it, it's part of a Macro Pack subscription, or you can try the app for free on the Atlassian Marketplace.

---

For those of you maintaining long, structured docs in Confluence, like specs, policies, and audit files, how are you numbering headings today? Manual numbering, an app, CSS/macros on Data Center, or something else? What's worked and what's burned you?