Table of Contents

The table of contents (TOC) provides an at-a-glance overview of a page's structure and enables quick navigation to specific sections. Mordoc automatically generates the TOC from your page headings.

How TOC Works

The TOC is automatically generated from the heading structure of each page:

# Page Title

## Section One
Content here...

## Section Two
Content here...

### Subsection 2.1
Content here...

### Subsection 2.2
Content here...

## Section Three
Content here...

This generates a TOC with all the headings, allowing readers to jump directly to any section.

Default Behavior

By default, the TOC:

• Automatically generates from page headings
• Shows Level 2 and Level 3 headings (## and ###)
• Displays on the right side of the page
• Highlights current section as you scroll
• Sticky positioning - stays visible while scrolling
• Hides on mobile - Shows only on tablets and desktops

Heading Levels in TOC

What's Included by Default

Level 1 headings are used as the page title and don't appear in the TOC. Levels 4-6 are typically too detailed for the TOC.

Configuration

Customize TOC behavior through the configuration file.

Edit config/styles/main.json:

{
  "toc": {
    "enabled": true,
    "minHeadingLevel": 2,
    "maxHeadingLevel": 3,
    "position": "right",
    "width": "240px",
    "title": "On This Page",
    "showOnMobile": false
  }
}

Configuration Properties

Show More Heading Levels

To include Level 4 headings:

{
  "toc": {
    "maxHeadingLevel": 4
  }
}

Show Only Major Sections

To show only Level 2 headings:

{
  "toc": {
    "minHeadingLevel": 2,
    "maxHeadingLevel": 2
  }
}

Disable TOC

To disable the TOC completely:

{
  "toc": {
    "enabled": false
  }
}

Per-Page TOC Control

Disable the TOC for specific pages using frontmatter:

---
title: My Page
toc: false
---

# My Page

This page won't show a table of contents.

This is useful for:

• Short pages that don't need a TOC
• Landing pages with different layouts
• Pages with custom navigation

Styling the TOC

Customize TOC appearance:

{
  "toc": {
    "title": "On This Page",
    "titleColor": "#111827",
    "titleSize": "0.875rem",
    "titleWeight": "600",
    "linkColor": "#6b7280",
    "activeLinkColor": "#3b82f6",
    "hoverLinkColor": "#111827",
    "fontSize": "0.8125rem",
    "lineHeight": "1.75",
    "indent": "1rem"
  }
}

Style Properties

TOC Behavior

Active Section Highlighting

As users scroll, the TOC automatically highlights the current section:

• Scroll detection: Detects which section is currently visible
• Active indicator: Current section is highlighted
• Smooth transition: Color transitions smoothly between sections

Smooth Scrolling

Clicking a TOC link smoothly scrolls to that section:

• Smooth animation: Not instant jump
• Offset adjustment: Accounts for fixed headers
• Focus management: Updates browser history

Sticky Positioning

The TOC remains visible while scrolling:

• Fixed position: Stays in view as you scroll
• Respects viewport: Scrollable if too long
• Smart positioning: Doesn't overlap content

Best Practices

Writing TOC-Friendly Headings

Good headings:

## Installation
## Configuration
## Usage Examples
## Troubleshooting

Poor headings:

## Installation (This section explains how to install the software on your computer)
## Config
## Examples
## Problems You Might Encounter and How to Fix Them

Keep headings:

• Concise (3-6 words ideal)
• Descriptive
• Parallel in structure
• Consistent in style

Logical Heading Structure

Create a clear hierarchy:

# API Guide

## Authentication
### API Keys
### OAuth Flow

## Endpoints
### Users
### Projects
### Files

## Rate Limiting
### Default Limits
### Custom Plans

This creates a scannable TOC that reflects your content structure.

Avoid Too Many Headings

Good (scannable):

## Overview
## Getting Started
## Core Concepts
## Advanced Topics
## API Reference

Poor (overwhelming):

## Section 1
## Section 2
## Section 3
## Section 4
## Section 5
## Section 6
## Section 7
## Section 8
## Section 9
## Section 10

Aim for 5-10 major sections per page.

Responsive Behavior

Desktop (> 1024px)

• TOC visible in right sidebar
• Fixed position while scrolling
• Full width (default 240px)

Tablet (768px - 1024px)

• TOC may be hidden or collapsible
• Reduced width
• Toggle button to show/hide

Mobile (< 768px)

• TOC hidden by default
• Accessible via dropdown or modal
• Saves screen space for content

Configure mobile behavior:

{
  "toc": {
    "showOnMobile": true,
    "mobilePosition": "dropdown"
  }
}

Accessibility

The TOC is built with accessibility in mind:

• Semantic HTML: Uses proper navigation landmarks
• Keyboard Navigation: Fully keyboard accessible
• Screen Readers: ARIA labels for context
• Focus Indicators: Clear focus states
• Skip Links: Option to skip TOC navigation

Use Cases

Long Documentation Pages

For comprehensive guides:

# Complete User Guide

## Installation
### System Requirements
### Download
### Installation Steps

## Configuration
### Basic Settings
### Advanced Options
### Environment Variables

## Usage
### Getting Started
### Common Tasks
### Advanced Features

## Troubleshooting
### Common Issues
### Error Messages
### Support

The TOC helps users navigate long content efficiently.

API Documentation

For endpoint documentation:

# Users API

## Overview
## Authentication
## Endpoints
### List Users
### Get User
### Create User
### Update User
### Delete User
## Error Codes
## Rate Limits

TOC provides quick access to specific endpoints.

Tutorial Pages

For step-by-step guides:

# Build Your First App

## Before You Begin
## Step 1: Setup
## Step 2: Create Project
## Step 3: Add Features
## Step 4: Test
## Step 5: Deploy
## Next Steps

TOC shows progress through the tutorial.

Troubleshooting

TOC Not Showing

• Check enabled: true in configuration
• Verify page has Level 2 or 3 headings
• Ensure page isn't too short (< 3 headings)
• Check page frontmatter doesn't have toc: false

Headings Missing from TOC

• Verify heading levels match configuration
• Check heading markdown syntax is correct
• Ensure headings aren't inside code blocks
• Rebuild site: npm run build

TOC Not Highlighting Current Section

• Check JavaScript is enabled
• Verify scroll event listeners are working
• Clear browser cache
• Check for CSS conflicts

TOC Overlapping Content

• Adjust TOC width in configuration
• Check viewport size and responsive breakpoints
• Verify page layout CSS
• Consider hiding TOC on smaller screens

Examples

Basic TOC Configuration

{
  "toc": {
    "enabled": true,
    "minHeadingLevel": 2,
    "maxHeadingLevel": 3,
    "title": "Contents",
    "position": "right"
  }
}

Detailed TOC (Include Level 4)

{
  "toc": {
    "enabled": true,
    "minHeadingLevel": 2,
    "maxHeadingLevel": 4,
    "title": "Page Contents"
  }
}

Minimal TOC (Major Sections Only)

{
  "toc": {
    "enabled": true,
    "minHeadingLevel": 2,
    "maxHeadingLevel": 2,
    "title": "Sections"
  }
}

Custom Styled TOC

{
  "toc": {
    "title": "Jump To",
    "titleColor": "#059669",
    "activeLinkColor": "#059669",
    "fontSize": "0.875rem",
    "width": "280px"
  }
}

Next Steps

• Search Configuration - Set up search functionality
• Branding - Customize logo and colors
• Side Navigation - Configure main navigation