Skip to main content

Confluence Numbered Headings: Auto-Number H1-H6 Pages

· 10 min read
NGPilot
NGPilot
NGPilot

If you have ever written a long Confluence page — a technical specification, an SOP, a project charter, or an onboarding guide — you know the problem. You add headings, rearrange sections, insert a new subsection, and suddenly every manual number is wrong. "Section 3.2" becomes "Section 4.2" because you added a new section above it, and you spend the next twenty minutes renumbering everything by hand.

Numbered headings solve this. When your heading numbers are generated automatically, you can add, remove, and reorder sections freely without ever touching a number again. The numbering updates itself.

This tutorial walks through how to set up automatic numbered headings in Confluence using Modern Numbered Headings for Confluence, an NGPILOT app that installs in seconds and works immediately — no configuration wizards, no macro nesting, no custom CSS.

Why numbered headings matter for documentation​

Numbered headings are not just cosmetic. They serve a practical purpose in any document that people reference, discuss, or review:

  • Unambiguous references. When someone says "see section 2.3.1," there is no confusion about which section they mean. Compare that to "see the third subsection under Risk Assessment" — which risk assessment? Which level?
  • Easier navigation. A table of contents with numbered headings lets readers jump directly to the section they need. Numbers also communicate the hierarchy at a glance: 2.3 is clearly a child of section 2.
  • Professional appearance. Technical documentation, legal documents, compliance reports, and formal proposals all use numbered headings as a standard convention. If your Confluence pages serve any of these purposes, numbered headings make them look polished.
  • Cross-referencing. In regulated environments (ISO, SOC 2, GDPR documentation), section numbers are required for traceability. Automated numbering ensures your cross-references stay accurate as the document evolves.

Without an app, Confluence does not number headings natively. You can add numbers manually in the heading text, but every structural edit breaks them. That is where Modern Numbered Headings comes in.

Step-by-step: Set up numbered headings in Confluence​

Step 1: Install Modern Numbered Headings for Confluence​

  1. Go to Confluence Settings (the gear icon in the top-right corner).
  2. Navigate to Find new apps (under the "Apps" section).
  3. Search for "Modern Numbered Headings".
  4. Click Install and follow the prompts.

The app installs globally and is available on every Confluence page immediately. No per-space configuration is needed.

After installation, open any page that has headings. Look for the app icon (a clipboard symbol) in the page byline — the area just below the page title. If you see it, the installation was successful.

Step 2: Open a Confluence page with headings​

Open or create a Confluence page that uses multiple heading levels. A good test page should have at least an H1, several H2 sections, and a few H3 subsections.

Example heading structure:

Project Deployment Guide (H1)
  Prerequisites (H2)
    System Requirements (H3)
    Access Credentials (H3)
  Installation (H2)
    Step 1: Download (H3)
    Step 2: Configure (H3)
  Troubleshooting (H2)

You do not need to add any numbers manually. The app will generate them.

Step 3: Configure the numbering scheme​

Click the app icon in the page byline. A configuration modal opens with all available options.

Numbering style selection lets you choose from five professional formats. The most common choice is Decimal (1, 1.1, 1.1.1), but you can pick any style that fits your document type. A live preview shows exactly how your headings will look with each scheme.

Heading level selection lets you control which levels are numbered. For most documents, H1 through H3 is sufficient. For deeply nested technical specifications, you can extend numbering all the way to H6.

Display options include a toggle for hierarchical indentation in the generated table of contents. Enable it for complex documents; disable it for simpler pages where you want a flat list.

Step 4: Apply numbering to headings​

Once you have selected your numbering style and heading levels, click Insert TOC in the modal. The app does two things:

  1. It inserts a formatted, numbered table of contents at the top of your page.
  2. It adds the corresponding numbers to each heading in the document body.

Every heading on the page gets numbered automatically based on the scheme you chose. If you later add a new H2 between sections 2 and 3, the app renumbers everything — section 3 becomes section 4, section 3.1 becomes 4.1, and so on. No manual intervention required.

To update the numbering after editing your page, click the app icon, select Remove TOC, then click Insert TOC again with your desired settings. The entire process takes about five seconds.

Step 5: Add a table of contents​

The app generates its own numbered table of contents directly on the page. If you also want to use Confluence's built-in Table of Contents macro, the two work together seamlessly.

To add Confluence's TOC macro:

  1. Place your cursor at the top of the page, above your content.
  2. Type /toc and select the Table of Contents macro.
  3. Configure the macro to display the heading levels you want.
  4. Save the page.

The TOC macro will display your headings with their numbering intact, giving readers a navigable overview of the entire document.

Numbering scheme reference​

Modern Numbered Headings supports five numbering styles. Each is suited to different document types.

1. Decimal (1, 1.1, 1.1.1)​

The most widely used format. Clear, unambiguous, and familiar to anyone who has read technical documentation.

1. Introduction
1.1. Overview
1.2. Scope
2. Architecture
2.1. Frontend
2.2. Backend

Best for: Technical documentation, user guides, SOPs, general business documents.

2. Roman Numerals (I, I.I, I.II)​

Formal and authoritative. Common in academic papers, executive summaries, and compliance documentation.

I. Executive Summary
I.I. Key Findings
I.II. Recommendations
II. Detailed Analysis
II.I. Methodology
II.II. Results

Best for: Formal reports, academic papers, board presentations, compliance documents.

3. Alphabetic (A, A.A, A.B)​

Uses letters instead of numbers for the top level. Useful for procedures, checklists, and documents where numeric sections might be confused with ordered lists.

A. Planning Phase
A.A. Requirements Gathering
A.B. Resource Allocation
B. Implementation Phase
B.A. Development
B.B. Testing

Best for: Procedures, checklists, project phases, structured lists.

4. Outline (1), 1.1), 1.1.1))​

Uses closing parentheses instead of periods. A legal-standard format that is common in contracts, policy documents, and regulatory filings.

1) Project Overview
1.1) Scope Definition
1.1.1) Deliverables
1.2) Timeline
2) Risk Assessment
2.1) Technical Risks
2.2) Business Risks

Best for: Legal documents, contracts, policies, regulatory filings, business reports.

5. Mixed (1, A, i, a)​

Each nesting level uses a different format: numbers at the top, then uppercase letters, then lowercase roman numerals, then lowercase letters. This is the traditional outline format taught in schools.

1. System Architecture
A. Frontend Components
i. User Interface
a. Navigation
b. Content Display
ii. Data Management
B. Backend Services
2. Security Framework

Best for: Complex hierarchies, detailed specifications, academic outlines, technical standards.

Tips for working with long documents​

Long Confluence pages (50+ headings, thousands of words) need a bit more planning to keep organized. Here are practical tips:

Break very long documents into multiple pages​

If your document exceeds roughly 5,000 words, consider splitting it into child pages under a parent page. Use Confluence's page hierarchy to maintain structure. Each child page gets its own numbered headings, and readers navigate between sections using the page tree.

For example, instead of one giant "Deployment Guide" page:

  • Deployment Guide (parent page, overview)
    • Prerequisites (child page)
    • Installation (child page)
    • Configuration (child page)
    • Troubleshooting (child page)

Always include a table of contents​

For any page with more than four headings, a table of contents is essential. Place it at the top of the page so readers can scan the structure before scrolling. The app generates the TOC with numbered headings, giving readers an instant overview of the document's scope and depth.

Maintain consistent heading hierarchy​

Do not skip heading levels. If your page has an H1 followed immediately by an H3 (skipping H2), the numbering will look broken to readers and the hierarchy becomes confusing. Always step through levels sequentially: H1 > H2 > H3 > H4.

Avoid using headings purely for visual styling. If you need larger text, use Confluence's paragraph formatting instead. Headings define document structure, and the numbering scheme depends on a clean hierarchy.

Filter heading levels in the TOC​

Not every heading needs to appear in the table of contents. For long documents, including only H1 through H3 keeps the TOC compact and scannable. You can configure this in the app's modal by checking or unchecking heading levels.

The deeper headings (H4, H5, H6) still get numbered in the document body — they just do not clutter the TOC.

Update the TOC after structural edits​

After adding, removing, or reordering sections, click the app icon and re-insert the TOC. This takes just a few seconds and ensures the table of contents reflects the current page structure. The old TOC is removed cleanly with no leftover artifacts.

Best practices for numbered headings in Confluence​

Beyond the mechanics of the app, these practices will make your numbered documentation consistently professional and easy to maintain.

1. Choose one numbering scheme per document type​

Pick a standard for each category of documentation your team produces. For example:

  • Technical specs: Decimal (1, 1.1, 1.1.1)
  • Compliance documents: Outline (1), 1.1), 1.1.1))
  • Project plans: Alphabetic (A, A.A, A.B)

Write the standard down in your team's style guide. Consistency across documents makes it easier for readers to navigate your Confluence space.

2. Start every numbered page with a clear title​

Use an H1 as the page title. This becomes the root of your numbering hierarchy. A page without a clear top-level heading produces confusing numbering — the first H2 gets numbered 0.1 or is orphaned entirely.

3. Keep heading text descriptive and concise​

Numbered headings like "3.2 Configuration" work well. Avoid vague headings like "3.2 Notes" or "3.2 Miscellaneous." Readers scanning the table of contents should understand the content of each section from the heading alone.

Do not include the numbers manually in the heading text. The app adds them automatically. Writing "1.1 Overview" as the heading text would result in "1.1 1.1 Overview" — duplicated numbering.

4. Limit nesting to three or four levels​

Deep nesting (H5, H6) makes documents harder to read and the table of contents unwieldy. If you find yourself routinely going beyond H4, consider whether the sub-content should be split into a separate child page.

A three-level structure (H1 > H2 > H3) covers the vast majority of business and technical documents. Reserve four or more levels for genuinely complex specifications.

5. Review the TOC before publishing​

Before publishing or sharing a long Confluence page, glance at the generated table of contents. Look for:

  • Missing sections (a heading was accidentally deleted)
  • Duplicate headings (two sections with the same title)
  • Skipped levels (H1 followed by H3)
  • Uneven structure (one section with five subsections while others have none)

The TOC is a structural x-ray of your document. Use it as a final quality check.