# User Guide - Modern Numbered Headings for Confluence

> **Complete guide to creating professional table of contents with multiple numbering styles**

## Table of Contents[​](#table-of-contents "Direct link to Table of Contents")

1. [Getting Started](#getting-started)
2. [Basic Usage](#basic-usage)
3. [Numbering Styles](#numbering-styles)
4. [Advanced Features](#advanced-features)
5. [Best Practices](#best-practices)
6. [Troubleshooting](#troubleshooting)
7. [FAQ](#faq)

## Getting Started[​](#getting-started "Direct link to Getting Started")

### Installation[​](#installation "Direct link to Installation")

1. **From Atlassian Marketplace**:

   * Go to **Confluence Settings** → **Find new apps**
   * Search for **"Modern Numbered Headings"**
   * Click **"Install"** and follow the prompts

2. **Verify Installation**:

   * Open any Confluence page with headings
   * Look for the app icon (📋) in the page byline under the title
   * If you see the icon, installation was successful!

### First Time Setup[​](#first-time-setup "Direct link to First Time Setup")

No setup required! The app works immediately after installation.

## Basic Usage[​](#basic-usage "Direct link to Basic Usage")

### Step 1: Open the App[​](#step-1-open-the-app "Direct link to Step 1: Open the App")

1. **Navigate** to any Confluence page that contains headings
2. **Look for the app icon** (📋) in the page byline section (under the page title)
3. **Click the icon** to open the configuration modal

### Step 2: Configure Your TOC[​](#step-2-configure-your-toc "Direct link to Step 2: Configure Your TOC")

The large modal interface provides all configuration options:

#### **Numbering Style Selection**[​](#numbering-style-selection "Direct link to numbering-style-selection")

* Choose from 5 professional numbering styles
* See live examples of each style format
* Select the style that best fits your document type

#### **Heading Level Selection**[​](#heading-level-selection "Direct link to heading-level-selection")

* Choose which heading levels to include (H1-H6)
* Use checkboxes to select any combination
* Only headings present on your page will be processed

#### **Display Options**[​](#display-options "Direct link to display-options")

* **Enable Indentation**: Toggle hierarchical indentation on/off
* **Live Preview**: See exactly how your TOC will look

### Step 3: Preview and Apply[​](#step-3-preview-and-apply "Direct link to Step 3: Preview and Apply")

1. **Review the preview** to see your TOC formatting
2. **Make adjustments** if needed (style, levels, indentation)
3. **Click "Insert TOC"** to add it to your page
4. **Page automatically reloads** to show the new TOC

### Step 4: Navigate and Manage[​](#step-4-navigate-and-manage "Direct link to Step 4: Navigate and Manage")

* **Click any TOC entry** to scroll to that section
* **Remove TOC**: Click the app icon again and select "Remove TOC"
* **Update TOC**: Remove and re-insert with new settings

## Numbering Styles[​](#numbering-styles "Direct link to Numbering Styles")

### 1. Decimal Style (Default)[​](#1-decimal-style-default "Direct link to 1. Decimal Style (Default)")

**Format**: `1. 1.1. 1.2.` **Best For**: Technical documentation, general use **Example**:

```
1. Introduction

1.1. Overview

1.2. Getting Started

2. Configuration

2.1. Basic Setup

2.2. Advanced Options
```

### 2. Roman Numerals[​](#2-roman-numerals "Direct link to 2. Roman Numerals")

**Format**: `I. I.I. I.II.` **Best For**: Formal documents, academic papers **Example**:

```
I. Executive Summary

I.I. Key Findings

I.II. Recommendations

II. Detailed Analysis

II.I. Methodology

II.II. Results
```

### 3. Alphabetic Style[​](#3-alphabetic-style "Direct link to 3. Alphabetic Style")

**Format**: `A. A.A. A.B.` **Best For**: Structured lists, procedures **Example**:

```
A. Planning Phase

A.A. Requirements Gathering

A.B. Resource Allocation

B. Implementation Phase

B.A. Development

B.B. Testing
```

### 4. Outline Style[​](#4-outline-style "Direct link to 4. Outline Style")

**Format**: `1) 1.1) 1.1.1)` **Best For**: Business reports, legal documents **Example**:

```
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
```

### 5. Mixed Style[​](#5-mixed-style "Direct link to 5. Mixed Style")

**Format**: `1. A. i. a.` **Best For**: Complex hierarchies, detailed specifications **Example**:

```
1. System Architecture

A. Frontend Components

i. User Interface

a. Navigation

b. Content Display

ii. Data Management

B. Backend Services

2. Security Framework
```

## Advanced Features[​](#advanced-features "Direct link to Advanced Features")

### Heading Level Filtering[​](#heading-level-filtering "Direct link to Heading Level Filtering")

**Purpose**: Control which heading levels appear in your TOC

**How to Use**:

1. In the configuration modal, find "Include Levels"
2. Check/uncheck heading levels (H1-H6)
3. Preview updates automatically
4. Only selected levels will appear in the TOC

**Best Practices**:

* **H1-H3**: Good for most documents
* **H1-H2**: Executive summaries, brief documents
* **H1-H6**: Comprehensive technical documentation
* **H2-H4**: Skip main title, focus on sections

### Indentation Control[​](#indentation-control "Direct link to Indentation Control")

**Purpose**: Control visual hierarchy in your TOC

**Options**:

* **Enabled**: Hierarchical indentation with proper spacing
* **Disabled**: Flat list without indentation

**When to Use**:

* **Enable**: Complex documents with multiple levels
* **Disable**: Simple documents, space-constrained layouts

### Live Preview[​](#live-preview "Direct link to Live Preview")

**Features**:

* **Real-time Updates**: Changes appear instantly
* **Accurate Formatting**: Exactly matches final result
* **Heading Count**: Shows total number of headings
* **Truncated Display**: Shows first 8 items for performance

### Smart Duplicate Prevention[​](#smart-duplicate-prevention "Direct link to Smart Duplicate Prevention")

**How it Works**:

* App detects existing TOCs using invisible markers
* "Insert TOC" button disabled when TOC already exists
* "Remove TOC" button disabled when no TOC present
* Clear status indicators show current state

### Magic Marker System[​](#magic-marker-system "Direct link to Magic Marker System")

**Technology**:

* Uses invisible unicode characters as boundaries
* Completely invisible to users
* Bulletproof TOC detection and removal
* No interference with page content

**Benefits**:

* **Reliable Detection**: Never fails to find TOCs
* **Clean Removal**: Removes all TOC elements perfectly
* **No Artifacts**: No leftover formatting or text
* **Future-Proof**: Works regardless of content changes

## Best Practices[​](#best-practices "Direct link to Best Practices")

### Document Structure[​](#document-structure "Direct link to Document Structure")

#### **Good Heading Structure**:[​](#good-heading-structure "Direct link to good-heading-structure")

```
# Main Title (H1)

## Section 1 (H2)

### Subsection 1.1 (H3)

### Subsection 1.2 (H3)

## Section 2 (H2)

### Subsection 2.1 (H3)

#### Detail 2.1.1 (H4)
```

#### **Avoid**:[​](#avoid "Direct link to avoid")

* Skipping heading levels (H1 → H3)
* Using headings for styling only
* Empty headings
* Duplicate heading text

### Numbering Style Selection[​](#numbering-style-selection-1 "Direct link to Numbering Style Selection")

#### **Choose Based on Document Type**:[​](#choose-based-on-document-type "Direct link to choose-based-on-document-type")

**Technical Documentation**:

* ✅ Decimal (1. 1.1. 1.2.)
* ✅ Outline (1) 1.1) 1.1.1))

**Business Reports**:

* ✅ Decimal (1. 1.1. 1.2.)
* ✅ Roman (I. I.I. I.II.)
* ✅ Outline (1) 1.1) 1.1.1))

**Academic Papers**:

* ✅ Roman (I. I.I. I.II.)
* ✅ Decimal (1. 1.1. 1.2.)

**Legal Documents**:

* ✅ Outline (1) 1.1) 1.1.1))
* ✅ Mixed (1. A. i. a.)

**Procedures/Checklists**:

* ✅ Alphabetic (A. A.A. A.B.)
* ✅ Decimal (1. 1.1. 1.2.)

### TOC Placement[​](#toc-placement "Direct link to TOC Placement")

#### **Best Practices**:[​](#best-practices-1 "Direct link to best-practices-1")

* **Top of Page**: Most common and expected location
* **After Introduction**: For documents with executive summary
* **Before Main Content**: Skip preliminary sections

#### **Avoid**:[​](#avoid-1 "Direct link to avoid-1")

* Multiple TOCs on same page
* TOC in the middle of content
* TOC at the very end

### Maintenance[​](#maintenance "Direct link to Maintenance")

#### **When to Update TOC**:[​](#when-to-update-toc "Direct link to when-to-update-toc")

* Added new sections
* Removed sections
* Changed heading text
* Restructured document

#### **How to Update**:[​](#how-to-update "Direct link to how-to-update")

1. Click app icon
2. Click "Remove TOC"
3. Make your content changes
4. Click app icon again
5. Click "Insert TOC" with new settings

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### Common Issues[​](#common-issues "Direct link to Common Issues")

#### **App Icon Not Visible**[​](#app-icon-not-visible "Direct link to app-icon-not-visible")

**Possible Causes**:

* Page has no headings
* App not installed properly
* Browser cache issues

**Solutions**:

1. **Check for headings**: Ensure page has H1-H6 headings
2. **Refresh page**: Clear browser cache and reload
3. **Check installation**: Verify app is installed in Confluence settings
4. **Contact admin**: May need admin permissions

#### **TOC Not Inserting**[​](#toc-not-inserting "Direct link to toc-not-inserting")

**Possible Causes**:

* No headings selected
* TOC already exists
* Insufficient permissions

**Solutions**:

1. **Select heading levels**: Ensure at least one level is checked
2. **Check for existing TOC**: Remove existing TOC first
3. **Verify permissions**: Ensure you can edit the page
4. **Try different browser**: Test in incognito/private mode

#### **Navigation Links Not Working**[​](#navigation-links-not-working "Direct link to navigation-links-not-working")

**Possible Causes**:

* Page modified after TOC insertion
* Browser compatibility issues
* Confluence caching

**Solutions**:

1. **Update TOC**: Remove and re-insert TOC
2. **Clear cache**: Refresh page and clear browser cache
3. **Check browser**: Ensure modern browser version
4. **Wait for sync**: Allow Confluence to process changes

#### **Formatting Issues**[​](#formatting-issues "Direct link to formatting-issues")

**Possible Causes**:

* Confluence theme conflicts
* Custom CSS interference
* Browser rendering differences

**Solutions**:

1. **Try different style**: Test with decimal numbering
2. **Disable custom CSS**: Temporarily disable page customizations
3. **Test in different browser**: Verify cross-browser compatibility
4. **Contact support**: Report persistent formatting issues

### Error Messages[​](#error-messages "Direct link to Error Messages")

#### **"No headings found on this page"**[​](#no-headings-found-on-this-page "Direct link to no-headings-found-on-this-page")

* **Cause**: Page contains no H1-H6 headings
* **Solution**: Add headings to your page content

#### **"No headings selected"**[​](#no-headings-selected "Direct link to no-headings-selected")

* **Cause**: All heading level checkboxes are unchecked
* **Solution**: Select at least one heading level

#### **"TOC Already Inserted"**[​](#toc-already-inserted "Direct link to toc-already-inserted")

* **Cause**: Page already contains a TOC
* **Solution**: Remove existing TOC before inserting new one

#### **"Failed to update page"**[​](#failed-to-update-page "Direct link to failed-to-update-page")

* **Cause**: Insufficient permissions or network issues
* **Solution**: Check edit permissions and network connection

### Performance Issues[​](#performance-issues "Direct link to Performance Issues")

#### **Slow Loading**[​](#slow-loading "Direct link to slow-loading")

* **Clear browser cache**
* **Check network connection**
* **Try in incognito mode**
* **Contact support if persistent**

#### **Large Documents**[​](#large-documents "Direct link to large-documents")

* **App optimized for 50+ headings**
* **Preview shows first 8 items for performance**
* **Full TOC still generated correctly**
* **Consider breaking very large documents into sections**

## FAQ[​](#faq "Direct link to FAQ")

### General Questions[​](#general-questions "Direct link to General Questions")

#### **Q: Is the app free?**[​](#q-is-the-app-free "Direct link to q-is-the-app-free")

A: Yes, there's a free tier with basic decimal numbering. Professional features require a paid subscription.

#### **Q: Does it work on mobile?**[​](#q-does-it-work-on-mobile "Direct link to q-does-it-work-on-mobile")

A: Yes, the app is fully responsive and works on tablets and mobile devices.

#### **Q: Can I customize the TOC title?**[​](#q-can-i-customize-the-toc-title "Direct link to q-can-i-customize-the-toc-title")

A: Currently, the TOC uses a standard format. Custom titles are planned for future releases.

#### **Q: Does it work with Confluence templates?**[​](#q-does-it-work-with-confluence-templates "Direct link to q-does-it-work-with-confluence-templates")

A: Yes, the app works with any Confluence page regardless of template.

### Technical Questions[​](#technical-questions "Direct link to Technical Questions")

#### **Q: How does the magic marker system work?**[​](#q-how-does-the-magic-marker-system-work "Direct link to q-how-does-the-magic-marker-system-work")

A: It uses invisible unicode characters to mark TOC boundaries, making detection and removal bulletproof.

#### **Q: Does the app store my data?**[​](#q-does-the-app-store-my-data "Direct link to q-does-the-app-store-my-data")

A: No, the app processes content in real-time only. No data is stored externally.

#### **Q: Is it GDPR compliant?**[​](#q-is-it-gdpr-compliant "Direct link to q-is-it-gdpr-compliant")

A: Yes, the app doesn't collect or store personal data, making it fully GDPR compliant.

#### **Q: What permissions does it need?**[​](#q-what-permissions-does-it-need "Direct link to q-what-permissions-does-it-need")

A: The app needs read/write permissions for Confluence content to insert and remove TOCs.

### Feature Questions[​](#feature-questions "Direct link to Feature Questions")

#### **Q: Can I have multiple TOCs on one page?**[​](#q-can-i-have-multiple-tocs-on-one-page "Direct link to q-can-i-have-multiple-tocs-on-one-page")

A: No, the app prevents duplicate TOCs to maintain document clarity.

#### **Q: Can I change numbering style after insertion?**[​](#q-can-i-change-numbering-style-after-insertion "Direct link to q-can-i-change-numbering-style-after-insertion")

A: Yes, remove the existing TOC and insert a new one with different settings.

#### **Q: Does it work with all heading levels?**[​](#q-does-it-work-with-all-heading-levels "Direct link to q-does-it-work-with-all-heading-levels")

A: Yes, the app supports H1 through H6 headings with full nesting.

#### **Q: Can I exclude certain headings?**[​](#q-can-i-exclude-certain-headings "Direct link to q-can-i-exclude-certain-headings")

A: Currently, you can exclude by level (H1-H6). Individual heading exclusion is planned for future releases.

### Troubleshooting Questions[​](#troubleshooting-questions "Direct link to Troubleshooting Questions")

#### **Q: What if the TOC doesn't appear after insertion?**[​](#q-what-if-the-toc-doesnt-appear-after-insertion "Direct link to q-what-if-the-toc-doesnt-appear-after-insertion")

A: The page automatically reloads after insertion. If it doesn't appear, try refreshing manually.

#### **Q: What if navigation links don't work?**[​](#q-what-if-navigation-links-dont-work "Direct link to q-what-if-navigation-links-dont-work")

A: This usually indicates the page was modified after TOC insertion. Remove and re-insert the TOC.

#### **Q: Can I undo TOC insertion?**[​](#q-can-i-undo-toc-insertion "Direct link to q-can-i-undo-toc-insertion")

A: Yes, click the app icon and select "Remove TOC" to cleanly remove it.

#### **Q: What if I see formatting issues?**[​](#q-what-if-i-see-formatting-issues "Direct link to q-what-if-i-see-formatting-issues")

A: Try a different numbering style or contact support with specific details about the issue.

## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts")

* [How to use numbered headings in Confluence](/blog/how-to-use-numbered-headings-confluence.md)
* [Confluence page navigation FAQ](/blog/faq-confluence-page-navigation-apps.md)

Was this helpful?👍 Yes👎 No