Table of Contents Generation

Although not part of the standard syntax, a table of contents (TOC) is useful for longer documents to help readers navigate the content and jump to specific parts. Many Markdown processors provide ways to automatically generate a TOC based on the headings in your document.

Manual vs automatic table of contents

There are two main approaches to creating a table of contents in Markdown:

1. Manual TOC - Create links yourself manually.
2. Automatic TOC - Auto-generated links using a specific syntax based on your Markdown processor.

Markdown-TOC directives

Many Markdown processors support special directives or syntax for TOC generation, such as:

[TOC]

When the Markdown is displayed, these placeholders are replaced with a generated table of contents.

How automatic TOCs work

Automatic TOC generators typically:

1. Scan your document for headings (#, ##, ###, etc.)
2. Create an anchor ID for each heading.
3. Generate a nested list of links pointing to these anchor links.

Automatic generation is specific to each processor, many having a unique syntax to generate a TOC.

Creating a manual TOC

You can manually create a toc if if your Markdown processor doesn't support automatic TOC generation. This is done with standard Markdown heading as the title, and a list of links:

Syntax:

## Table of Contents
- [Introduction](#introduction)
- [Getting Started](#getting-started)
  - [Installation](#installation)
  - [Editor Setup](#editor-setup)
- [Project Setup](#project-setup)
- [Advanced Features](#advanced-features)

This creates a TOC with links to various sections in the document. Using the anchor syntax (#) and the section name in lowercase, with spaces replaced by hyphens.

Styling and customizing TOCs

Many platforms allow TOC cutomization:

• Numbering - Auto add section numbering.
• Depth control - Limit which heading levels are added (e.g. only H2 and H3).
• Styling - Apply custom CSS styling.
• Collapsible sections - Allow expanding/collapsing of sections.

Using HTML

If supported in your processor, HTML can also be useful to create different styles of TOC:

Collapsible TOC using HTML

HTML details and summary can be used with platforms that support HTML and JavaScript:

<details>
  <summary>Table of Contents</summary>
  <p>TOC content</p>
</details>

Output:

Floating TOC with HTML

With HTML and CSS a toc can be created to float over the rest of the page content. This is done by fizing the CSS position to the top-right corner:

<div class="toc-wrapper">
  <section class="toc">
    <!-- TOC here -->
  </section>
</div>

With CSS to position it in the top-right corner:

.toc-wrapper {
  max-width: 400px;
  position: fixed;
  right: 25px;
  top: 25px;
}