How to Generate an Automatic Table of Contents in Markdown

Longer documents, such as research papers, white papers, and technical reports, require a clear navigation outline. Generating a Table of Contents (TOC) manually is tedious and error-prone, as page numbers and headings change during editing.

In this tutorial, you will learn how to generate an automatic table of contents markdown compilers and PDF exporters can construct.

Why You Need an Automatic Table of Contents

A dynamic, auto-generated TOC provides:

• Accuracy: The layout engine automatically matches headings with the correct page numbers during compilation.
• Convenience: Changing a heading’s text automatically updates the TOC.
• Improved PDF Usability: Many PDF exporters convert TOC entries into clickable bookmarks, allowing readers to jump to sections instantly.

Method 1: Using Pandoc --toc Command Line Flags

If you use Pandoc to convert your Markdown files to PDF, generating a TOC requires adding a single command-line flag.

Basic Pandoc TOC Generation

To include an auto-generated TOC at the start of your document, run:

pandoc document.md --toc -o document.pdf

The --toc (or --table-of-contents) flag tells Pandoc to scan all headings (#, ##, ###) in the Markdown file, format them as a table of contents, and insert it at the beginning of the PDF.

Customizing the TOC Depth

By default, Pandoc includes headings up to level 3 in the TOC. If you want to restrict it to only major sections (level 1 and 2), use the --toc-depth parameter:

pandoc document.md --toc --toc-depth=2 -o document.pdf

You can also specify the table of contents title in your document’s YAML frontmatter:

---
title: "Project Report"
toc-title: "Table of Contents"
---

Method 2: HTML and CSS Paged Media (Web-to-PDF Engines)

If you compile Markdown to HTML first and then use a CSS Paged Media engine (like Weasyprint) to create the PDF, you can generate a TOC using CSS target counters.

Create an HTML structure for the TOC in your Markdown:

<div class="toc">
  <h2>Contents</h2>
  <ul>
    <li><a href="#introduction">Introduction</a></li>
    <li><a href="#methodology">Methodology</a></li>
    <li><a href="#results">Results</a></li>
  </ul>
</div>

Then, use the following CSS rules to auto-calculate page numbers:

.toc ul {
  list-style: none;
  padding: 0;
}

.toc a::after {
  content: target-counter(attr(href), page);
  float: right;
}

/* Add dotted leaders between text and page numbers */
.toc li a {
  display: flex;
  justify-content: space-between;
}
.toc li a::after {
  content: target-counter(attr(href), page);
}

Method 3: Markdown Parsers & Static Generators (Jekyll/Hugo/Astro)

For publishing online or creating HTML-based documents, many Markdown parsers have built-in extensions to auto-generate a TOC:

• Kramdown (Jekyll): Add {::options toc_levels="1..3" /} at the top, and * TOC\n{:toc} where you want the TOC to appear.
• Goldmark (Hugo): Use the template variable {{ .TableOfContents }} in your single page layout.

Keep Your PDF Documents Organized

An automatic table of contents ensures that your document remains consistent and easy to navigate. If you want an editor that handles formatting automatically and exports clean PDFs with built-in navigation, check out the Markdown to PDF Editor.