Markdown Table of Contents: Manual and Auto Methods

A markdown table of contents gives readers quick links to every section in your document. You can build one by hand using standard markdown link syntax, or you can auto-generate one with tools built into GitHub, VS Code, Jekyll, and Hugo. This guide covers both approaches with copy-paste examples you can use right now.

Why Add a Markdown Table of Contents?

Long markdown documents are hard to navigate. According to the Nielsen Norman Group, users spend about 80% of their reading time above the fold. A table of contents at the top of your file fixes this by letting readers jump straight to the section they need.

A well-structured TOC also helps contributors understand your document layout at a glance. If you're writing README files, technical docs, or wiki pages, a TOC is practically required. It signals that you've organized your thoughts, and it saves everyone time.

How to Create a Manual Markdown Table of Contents

Building a markdown table of contents by hand is straightforward. You create an unordered list where each item links to a heading in your document.

Here's the basic pattern:

## Table of Contents

- [Getting Started](#getting-started)
- [Installation](#installation)
- [Configuration](#configuration)
  - [Basic Setup](#basic-setup)
  - [Advanced Options](#advanced-options)
- [FAQ](#faq)

The link target (the part in parentheses) follows these rules:

1. Convert the heading text to lowercase.
2. Replace spaces with hyphens.
3. Remove special characters like commas, periods, and exclamation marks.
4. Keep numbers and letters only.

For example, ## What's New in v2.0? becomes #whats-new-in-v20. You can test your links by previewing the file in your markdown editor before publishing.

When Manual TOC Makes Sense

Manual TOCs work best for short documents with fewer than 10 headings. They're portable across every platform that renders markdown. The downside? You need to update them every time you change a heading. For larger docs, auto-generation is the better path.

How Does GitHub Markdown Table of Contents Work?

GitHub added automatic table of contents support in 2021. You don't need to write anything extra. GitHub renders a TOC icon in the top-left corner of any markdown file or wiki page that has two or more headings.

Click the hamburger menu icon (three horizontal lines) next to the filename, and GitHub shows a sidebar with clickable links to every heading. See GitHub's documentation on READMEs for more details. This works on README files, wiki pages, and any .md file in a repository.

For GitHub wikis specifically, you can also insert a manual TOC using the [[_TOC_]] syntax if you want the TOC inline within the page content. About 73% of the top 1,000 GitHub repositories include some form of table of contents in their README files.

If you're writing docs that live outside GitHub, you can convert your markdown to HTML and add anchor links automatically during the conversion.

How to Auto-Generate a Table of Contents in VS Code

VS Code doesn't have built-in TOC generation, but extensions handle it well. The two most popular options are:

Markdown All in One (by Yu Zhang): This extension has over 4 million installs. Open any markdown file, press Ctrl+Shift+P, and run "Markdown All in One: Create Table of Contents." It inserts a TOC at your cursor position and updates it automatically when you save.

Markdown TOC (by AlanWalk): Similar functionality with more configuration options. You can customize the bullet style, depth level, and whether to include heading numbers.

Both extensions respect your heading hierarchy, so ## headings nest under # headings in the generated TOC. I personally prefer Markdown All in One because it handles edge cases better, especially with special characters in headings.

After generating your TOC, you can use the markdown formatter to clean up spacing and alignment across your entire document.

How to Add a Table of Contents in Jekyll

Jekyll, the static site generator behind GitHub Pages, supports automatic TOC through its Kramdown parser. Add this to any post or page:

* TOC
{:toc}

Kramdown reads your headings and generates a nested list with anchor links. You can exclude a heading from the TOC by adding {:.no_toc} below it:

## Section I Don't Want in the TOC
{:.no_toc}

You can also configure the TOC depth in your _config.yml file by setting toc_levels under the Kramdown options. Most Jekyll users limit it to h2 and h3 to keep the TOC manageable.

How to Add a Table of Contents in Hugo

Hugo provides a built-in .TableOfContents variable. The Hugo documentation on table of contents explains all configuration options. In your template, add:

{{ .TableOfContents }}

Hugo generates the TOC from your content headings automatically. You control the depth in config.toml:

[markup]
  [markup.tableOfContents]
    startLevel = 2
    endLevel = 4
    ordered = false

This configuration generates a TOC from h2 through h4 headings as an unordered list. Hugo's TOC is fast because it processes everything at build time, adding zero JavaScript to your pages.

For documents you plan to share as PDFs, you can convert markdown to PDF and the headings will carry over as bookmarks in most PDF viewers.

Tips for Better Markdown Tables of Contents

Keep these practices in mind when creating your TOC:

• Use descriptive headings. "Configuration" is better than "Section 3." Your TOC doubles as an outline, so make each entry informative.
• Limit TOC depth to 3 levels. Anything deeper clutters the list and makes it harder to scan.
• Place the TOC after your introduction. Readers want context before navigation. A sentence or two explaining the document purpose goes first.
• Update manually created TOCs. Stale links frustrate readers more than no TOC at all.

About 65% of developers say they check the table of contents before reading documentation, according to a 2023 Stack Overflow survey on docs usability.

Start Building Your Markdown Table of Contents

Whether you write your markdown table of contents by hand or let a tool generate it, the result is the same: a better reading experience. For quick projects, manual TOCs work fine. For living documents that change often, auto-generation with VS Code extensions, Jekyll, or Hugo saves real time. Try building one in our online editor and see how much easier your documents become to navigate.