How do I create a table of contents in Markdown?

Create anchor links to each heading using the format [Link Text](#heading-text). Heading text is converted to a URL anchor by lowercasing it, removing punctuation, and replacing spaces with hyphens. List all heading links at the top of your document.

Does GitHub automatically generate a table of contents?

Yes. GitHub automatically generates a table of contents for README files and wiki pages with multiple headings. Click the hamburger menu icon (three horizontal lines) in the top-left corner of any rendered Markdown file to see it.

Can I nest items in a Markdown TOC?

Yes. Indent sub-items with spaces to create a nested hierarchy. For example, indent h3 links with two spaces under their parent h2 link. This mirrors the document's heading structure visually.

Are there automatic Markdown TOC generators?

Yes. Several online tools can generate a TOC from your Markdown content. Paste your document, click generate, and copy the TOC links. VS Code extensions like Markdown TOC also automate this process.

Do Markdown TOC links work in all platforms?

Most platforms that render Markdown support anchor linking: GitHub, GitLab, Bitbucket, VS Code preview, and static site generators like Jekyll and Hugo. Some platforms auto-generate anchors, while others require explicit HTML anchor IDs.

How do I create a table of contents for a GitHub wiki?

Place your TOC links at the top of each wiki page. For wiki-wide navigation, use the _Sidebar.md file with links to all pages. GitHub also auto-generates a TOC for wiki pages with multiple headings.

How to Create a Markdown Table of Contents (TOC) for Any Document

Long Markdown documents — README files, documentation pages, and blog posts — benefit greatly from a table of contents (TOC). A well-structured TOC helps readers navigate quickly, improves the reading experience, and signals to search engines that your content is well-organized.

      This guide covers **how to create a Markdown table of contents** using manual anchor links, automatic generators, and platform-specific features like GitHub's auto-TOC.
    

    ## Method 1: Manual Anchor Link TOC (Universal)

    
      The most reliable method works on any Markdown renderer. Create a list of links at the top of your document, each pointing to a heading's anchor ID.
    

    ```

Introduction
Installation
Usage
Configuration
FAQ

        
          Markdown renderers automatically generate anchor IDs from heading text by:
        

        1. Converting to lowercase
2. Removing punctuation
3. Replacing spaces with hyphens
4. Deduplicating identical headings with numeric suffixes (e.g., `heading-1`, `heading-2`)

        
          For example, the heading `## Getting Started` becomes the anchor `#getting-started`. Link to it with `[Getting Started](#getting-started)`.
        

        ## Method 2: Nested TOC for Multi-Level Headings

        
          For documents with sub-sections, create a nested table of contents by indenting lower-level headings:
        

        ```
## Table of Contents
- [Getting Started](#getting-started)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
- [Usage](#usage)
  - [Basic Commands](#basic-commands)
  - [Advanced Options](#advanced-options)
- [API Reference](#api-reference)
  - [Authentication](#authentication)
  - [Endpoints](#endpoints)

      Use two spaces of indentation for h3 items under their h2 parent. This creates a visual hierarchy that mirrors the document structure.
    

    ## Method 3: Using Automatic TOC Generators

    
      For very long documents, manual TOC creation is tedious. Several tools automate the process:
    

    - **Online TOC generators:** Paste your Markdown into a web tool, and it outputs a complete TOC with proper anchor links

VS Code extensions: Install Markdown TOC or Markdown All in One, then run the "Create Table of Contents" command
Node.js packages: Use doctoc (npm) to generate and insert TOCs from the command line

GitHub Actions: Automate TOC generation on every push using a workflow action

  ## GitHub Auto-Generated TOC

  
    GitHub now **automatically generates a table of contents** for any Markdown file with multiple headings. Look for the hamburger menu icon (three horizontal lines) in the top-left corner of the rendered file. Clicking it expands a sidebar TOC with links to every heading in the document.
  

  
    This means you may not need a manual TOC for GitHub-specific files. However, if you want a TOC that appears in the document itself (e.g., for printed versions or copied content), use the manual method.
  

  ## Method 4: Custom HTML Anchor IDs

  
    Some Markdown renderers let you set custom anchor IDs using HTML:
  

  ```

<h2 id="my-custom-id">Heading Text</h2> ```

      Then link to it with `[Heading Text](#my-custom-id)`. This is useful when auto-generated anchors are too long or conflict with other headings. Note that not all platforms support custom HTML headings — test on your target platform first.
    

    ## Tips for Best Results

    - **Place the TOC at the top:** Put the table of contents immediately after your document title and before the first content section.

Keep it current: Every time you add, remove, or rename a heading, update the TOC. Automated tools help avoid stale links.
Include a "Back to Top" link: Add [↑ Back to Top](#table-of-contents) at the end of each major section for easier navigation.
Limit depth: For most documents, including h2 and h3 headings is sufficient. Including h4 and beyond makes the TOC cluttered.
Use descriptive link text: Link text should match the heading text exactly to avoid confusing readers.
Test your anchors: Click each TOC link to verify it jumps to the correct heading. Special characters in headings can cause anchor mismatches.
```
  ## Related Guides

  - [The Complete Markdown Cheat Sheet](/blog/complete-markdown-cheat-sheet)
```
Markdown for Technical Writing
Markdown Tables for Documentation
Online Markdown Editor and Preview

How to Create a Markdown Table of Contents (TOC) for Any Document

Table of Contents

Frequently Asked Questions