Skip to main content

User Guide - Modern Numbered Headings for Confluence

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

📚 Table of Contents​

  1. Getting Started
  2. Basic Usage
  3. Numbering Styles
  4. Advanced Features
  5. Best Practices
  6. Troubleshooting
  7. FAQ

🚀 Getting Started​

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​

No setup required! The app works immediately after installation.

🎯 Basic Usage​

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​

The large modal interface provides all configuration options:

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​

  • 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​

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

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​

  • 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​

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​

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​

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​

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​

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​

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​

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​

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​

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​

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​

Document Structure​

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:​

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

Numbering Style Selection​

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​

Best Practices:​

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

Avoid:​

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

Maintenance​

When to Update TOC:​

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

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​

Common Issues​

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​

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

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​

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​

"No headings found on this page"​

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

"No headings selected"​

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

"TOC Already Inserted"​

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

"Failed to update page"​

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

Performance Issues​

Slow Loading​

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

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​

General Questions​

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?​

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

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?​

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

Technical Questions​

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?​

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

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?​

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

Feature Questions​

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?​

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

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?​

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

Troubleshooting Questions​

Q: What if the TOC doesn't appear after insertion?​

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

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

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?​

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