Skip to main content

Confluence Page Navigation FAQ: TOC, Numbered Headings & Structure

· 15 min read
NGPilot
NGPilot
NGPilot

Page navigation is one of those things that nobody notices when it works well and everyone complains about when it does not. In Confluence, where pages routinely grow to thousands of words — technical specifications, onboarding guides, compliance documentation, project charters — helping readers find the right section quickly is not a nice-to-have. It is the difference between a knowledge base that people use and one that people ignore.

Confluence provides some building blocks for navigation: headings, a basic table of contents macro, anchor links, and an expand macro for collapsible content. These are functional, but they leave significant gaps. There is no automatic heading numbering. There is no way to create professional accordion-style FAQ sections without manual formatting. There is no structured system that ties together a table of contents, numbered headings, and collapsible sections into a cohesive reading experience.

This FAQ answers the most common questions about improving page navigation in Confluence. We cover how to add and configure tables of contents, how auto-numbered headings work, how to create collapsible sections, how anchor links function, and how to combine these techniques for long pages. Along the way, we reference two NGPILOT apps — Modern Numbered Headings for Confluence and Modern FAQ for Confluence — that fill the gaps left by Confluence's built-in tools.

How do I add a table of contents to a Confluence page?​

Confluence includes a built-in TOC macro that generates a table of contents from the headings on your page. To insert it, open the page editor and type /toc to bring up the macro. Once added, it scans your page for headings (H1 through H6) and renders them as a clickable list. Readers can click any entry to jump directly to that section.

The built-in TOC macro supports basic configuration. You can set the minimum and maximum heading levels to include, choose between flat and hierarchical display, and control whether the TOC entries are numbered or plain. These options cover simple use cases, but they have limitations:

  • No automatic heading numbering. The TOC can display numbers, but those numbers are generated by the macro itself and do not appear in the actual page headings. If you want numbered headings that appear both in the TOC and in the page body, you need a separate solution.
  • Limited formatting control. You cannot change the font, colors, or indentation style beyond the basic options. Teams that want a branded or polished look will find the defaults constraining.
  • Manual updates. If you restructure your page significantly, the TOC usually updates on page refresh, but complex nested structures can sometimes display incorrectly until the page is re-published.

For teams that want numbered headings inside the TOC, Modern Numbered Headings for Confluence integrates directly with the TOC macro. Instead of typing numbers into your headings manually, the app generates them automatically based on your chosen scheme. When you insert a TOC macro on a page that uses Modern Numbered Headings, the TOC entries display with the same numbering that appears in the page body — creating a consistent, professional navigation experience.

The workflow is straightforward: install the app, click the app icon in the page byline to configure your numbering scheme, insert the TOC macro at the top of your page, and publish. The TOC picks up the numbered headings automatically, and every structural change you make to the page updates the numbers without any manual intervention.

Can I auto-number headings in Confluence?​

Confluence does not number headings natively. You can add numbers manually by typing them into the heading text — for example, typing "1.1 System Requirements" as an H2 heading — but this approach breaks the moment you insert, delete, or reorder sections. Every edit becomes a renumbering exercise, and on long documents, that exercise can consume significant time.

Modern Numbered Headings for Confluence automates this entirely. After installing the app from the Atlassian Marketplace, a clipboard icon appears in the page byline on every Confluence page. Clicking it opens a configuration modal where you select your preferred numbering scheme and heading levels.

The app offers five numbering styles:

  1. Decimal (1, 1.1, 1.1.1) — the most widely used format for technical documentation, project plans, and general business documents. It communicates hierarchy depth at a glance.
  2. Roman numerals (I, I.I, I.II) — suited for formal documents, academic papers, executive summaries, and any context where a traditional appearance is preferred.
  3. Alphabetic (A, A.A, A.B) — commonly used for structured procedures, checklists, and process documentation where letters differentiate major sections.
  4. Outline (1), 1.1), 1.1.1)) — a format frequently seen in business reports and legal documents where the closing parenthesis style is the standard convention.
  5. Mixed (1, A, i, a) — designed for complex hierarchies with many nesting levels, where alternating between number and letter formats at each level improves readability.

All five styles support the full range of heading levels from H1 through H6. A live preview in the configuration modal shows exactly how your page will look with each scheme, so you can compare options before committing. Once you apply a scheme, the numbers appear on the published page automatically. Adding a new section between 2.1 and 2.2 shifts the numbering for 2.2, 2.3, and so on — without any manual work.

The numbers also appear in the built-in TOC macro and in anchor links. This consistency is what makes automatic numbering valuable: references like "see section 3.2.1" remain accurate even as the document evolves.

How do I create collapsible sections in Confluence?​

Confluence provides a built-in expand macro that creates a single collapsible section. Type /expand in the editor, give the section a title, and add content inside. When readers view the page, the section appears collapsed with only the title visible. Clicking the title expands the section to reveal the content underneath.

The expand macro works for individual collapsible sections, but it has clear limitations when you need multiple collapsible items on a page:

  • No accordion behavior. Expanding one section does not collapse the others. On pages with many expand macros, readers end up with a long, fully expanded page that defeats the purpose of collapsible content.
  • No bulk management. Each expand macro is independent. There is no way to reorder them with drag and drop, apply a consistent theme, or manage them as a group.
  • Inconsistent appearance. Because each expand macro is manually configured, the visual style can vary across pages and authors.

Modern FAQ for Confluence addresses these limitations with a dedicated macro designed for FAQ sections and collapsible content groups. The app provides two display themes:

  • Accordion theme — clicking one question expands its answer and collapses any previously expanded answer. This keeps the page compact and focused, which is ideal for FAQ pages where readers typically look for one specific answer.
  • Centered theme — all answers are visible on the page in a structured, formatted layout. This works well for pages where readers benefit from scanning all the content at once.

The app also includes drag-and-drop reordering in the editor. You can add questions, rearrange them by dragging, and delete individual items without touching the surrounding content. Each answer supports full Confluence rich text formatting, including links, images, tables, and code blocks.

To use Modern FAQ for Confluence, type /Modern FAQ for Confluence in the editor. Select your preferred theme by clicking the theme image in the configuration panel. Add your questions and answers one by one, using the plus button to add new items and the minus button to remove the last one. Click OK to apply. After insertion, you can drag and drop items to reorder them on the published page.

Can I link to specific sections of a Confluence page?​

Yes, and this is one of the most underused navigation features in Confluence. Every heading on a Confluence page automatically receives an anchor — a fragment identifier that you can use in URLs to link directly to that heading's position on the page.

To get the anchor link for a heading, navigate to the published page and hover over the heading. A small link icon appears to the left of the heading text. Clicking this icon updates your browser's address bar with the full URL including the anchor fragment. Copy this URL and share it in Slack, email, Jira tickets, or other Confluence pages. When someone clicks the link, they land on the page scrolled directly to that heading.

You can also construct anchor links manually. Confluence generates anchors from the heading text by converting to lowercase, replacing spaces with hyphens, and removing special characters. For example, a heading "System Requirements" gets the anchor #SystemRequirements. The full URL would look like https://your-domain.atlassian.net/wiki/spaces/TEAM/pages/12345#SystemRequirements.

When you use Modern Numbered Headings for Confluence, the anchor links incorporate the numbering, making them more descriptive and stable. A link to section 2.1 reads as #2.1SystemRequirements rather than just #SystemRequirements. This is especially useful in technical documentation where section numbers are the primary way people reference content. When a colleague asks "can you send me the link to section 3.2.1?", the anchor link directly reflects that numbering.

For pages that use Modern FAQ for Confluence, each FAQ item also has a distinct position on the page. While FAQ items are not standard headings and do not generate anchors in the same way, the collapsible sections keep content organized so readers can scan question titles quickly without needing to jump to specific FAQ entries via URL.

How do I improve navigation for long Confluence pages?​

Long pages are where navigation matters most — and where Confluence's built-in tools fall short on their own. A 4,000-word technical specification with 30 headings, multiple tables, and embedded diagrams can overwhelm readers if there is no structured way to navigate through it. The key is to combine multiple navigation techniques into a layered approach.

Add a table of contents at the top. This is the most fundamental step. Insert the built-in TOC macro at the very beginning of the page, before any content. Configure it to display all heading levels used on the page. Readers arriving at the page can immediately see the full structure and jump to any section.

Use numbered headings for structured references. Install Modern Numbered Headings for Confluence and apply a decimal numbering scheme. This gives every section a unique identifier. The numbered headings appear in the TOC, in the page body, and in anchor links. When someone references "section 4.2.3" in a meeting or a Jira comment, there is zero ambiguity about what they mean.

Break very long pages into child pages. If a page exceeds roughly 5,000 words, consider splitting it into child pages under a parent overview. The parent page contains a summary, the table of contents linking to child pages, and links to each section. This approach works well for multi-chapter documentation, API references, and comprehensive process guides. Confluence's page tree navigation in the sidebar then becomes an additional navigation layer.

Use collapsible sections for optional content. Not every reader needs every section. Appendices, troubleshooting guides, and advanced configuration details can be wrapped in collapsible sections so they do not clutter the main reading flow. For FAQ-style content, Modern FAQ for Confluence provides accordion behavior that keeps the page compact.

Add a "back to top" convention. While Confluence does not have a built-in back-to-top button, you can place a text link at the end of each major section that links back to the top of the page using an anchor. This small addition significantly improves the experience for readers who are scanning through a long document section by section.

What is the best numbering format for technical documentation?​

The short answer is decimal numbering: 1, 1.1, 1.1.1. This is the dominant format in technical documentation across software, engineering, manufacturing, and healthcare. It is used in ISO standards, RFC documents, military specifications, and the vast majority of technical writing style guides.

Decimal numbering works so well because it encodes hierarchy depth directly into the section number. When you see "3.4.2," you immediately know three things: this is in chapter 3, it is the fourth major subsection of chapter 3, and it is the second item within that subsection. No other numbering format communicates this information as efficiently.

That said, different documentation contexts have different conventions, and Modern Numbered Headings supports all of them:

  • Decimal (1, 1.1, 1.1.1) for technical documentation, software specifications, user guides, and API docs. This is the default and most versatile choice.
  • Roman numerals (I, I.I, I.II) for executive summaries, board papers, academic publications, and any formal context where roman numerals are the expected convention.
  • Alphabetic (A, A.A, A.B) for procedural checklists, training materials, and process documentation where sections represent distinct phases or stages.
  • Outline (1), 1.1), 1.1.1)) for legal documents, compliance reports, and business proposals where the outline format is the industry standard.
  • Mixed (1, A, i, a) for highly detailed specifications with four or more nesting levels, where alternating between numbers, letters, and roman numerals at each level prevents confusion between adjacent levels.

If you are unsure which format to choose, start with decimal. You can always switch later by clicking the app icon in the page byline and selecting a different scheme. The live preview shows the result before you commit, so there is no risk of choosing the wrong format and needing to undo formatting changes manually.

Page structure best practices​

Good page navigation starts with good page structure. No amount of tooling can fix a document where headings are used inconsistently, sections are organized illogically, or the hierarchy is too deep to follow. These five practices form the foundation for navigable Confluence pages.

1. Use a consistent heading hierarchy. Every page should follow a clear hierarchy: H1 for the page title, H2 for major sections, H3 for subsections, and so on. Never skip levels — jumping from H1 directly to H3 confuses both readers and assistive technology. If your H1 is "Deployment Guide," your H2s should be "Prerequisites," "Installation Steps," and "Troubleshooting," not random text styled as headings.

2. Keep nesting to three levels. Most documents work well with H1, H2, and H3. If you find yourself adding H4 and H5 headings regularly, the page is probably too complex for a single Confluence page. Consider splitting it into child pages or consolidating some subsections into their parent sections. Three levels of nesting is readable; six levels is not.

3. Write descriptive heading text. Headings serve as navigation signposts. "Configuration" tells the reader something. "Configuring Database Connections for High Availability" tells them exactly what to expect. Descriptive headings make the TOC more useful and anchor links more meaningful when shared in conversations.

4. Place the TOC before the main content. Readers expect to find the table of contents at the top of the page. Placing it after an introduction or in the middle of the content means readers have to scroll past content they may not need to find the navigation tool that helps them skip to the content they do need.

5. Review and update structure when content changes. Pages are living documents. When you add a new section, remove an outdated one, or reorganize the flow, take 30 seconds to check the heading hierarchy and TOC. With Modern Numbered Headings, the numbering updates automatically — but you still need to verify that the overall structure makes sense for the updated content.

NGPILOT apps for better page structure​

AppWhat it doesKey features
Modern Numbered Headings for ConfluenceAutomatically numbers headings on Confluence pages5 numbering schemes (decimal, roman, alphabetic, outline, mixed), live preview, heading level filtering, TOC macro integration, one-click insert and remove
Modern FAQ for ConfluenceCreates professional FAQ sections with collapsible contentAccordion and centered display themes, drag-and-drop reordering, rich text answers with images and links, consistent formatting across pages

These two apps address the two most common navigation gaps in Confluence. Modern Numbered Headings gives your pages a structured, numbered hierarchy that makes the TOC useful and cross-references unambiguous. Modern FAQ gives you a clean way to organize question-and-answer content without manual formatting or expand macro stacking.

Both apps install from the Atlassian Marketplace in under a minute and work immediately with no per-space configuration. They are designed to complement Confluence's built-in tools rather than replace them — the TOC macro, anchor links, and page tree navigation all continue to work as expected.