Guide

How to Add a Table of Contents to a Markdown PDF

July 5, 2026 · 4 min read

A table of contents turns a long Markdown document into something readers can actually navigate. In a PDF, a good one is clickable — tap an entry and jump to the section. This guide covers every way to generate a TOC on the way from Markdown to PDF, from a single Pandoc flag to a hand-built anchor list you control precisely.

First, understand how TOC links work

A table of contents is just a list of links that point to headings. For those links to work, each heading needs an id (an anchor), and each TOC entry links to #that-id. Most tools generate these ids automatically by "slugifying" the heading text — ## Getting Started becomes the anchor #getting-started. Once you know that, every method below is a variation on the same idea.

Method 1 — Pandoc's --toc flag

If you convert with Pandoc, a table of contents is one flag away:

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

• --toc inserts a generated, linked table of contents.
• --toc-depth=2 includes H1 and H2 headings (raise it to 3 for subsections).

Pandoc places the TOC at the top and wires up all the internal links for you. This is the most automatic route if you're already using Pandoc.

Method 2 — the [TOC] / [[toc]] marker

Several editors and renderers support a placeholder that expands into a table of contents where you put it. In VS Code with the Markdown All in One extension, run "Markdown All in One: Create Table of Contents" and it inserts (and keeps updated) a linked TOC at your cursor. Other markdown-it–based tools recognize a [[toc]] or [TOC] marker.

The advantage: the TOC lives in your Markdown, so it's visible in the source and travels with the file. Just remember it's tool-specific — a plain converter that doesn't recognize the marker will print the literal text [TOC].

Method 3 — build it by hand (works everywhere)

The most portable approach — and the one that works in any converter — is to write the TOC yourself as a normal Markdown list of links. Because heading ids are predictable slugs, you can point to them directly:

## Contents

- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)

## Introduction
...

## Getting Started
...

Each link's target is the lowercased heading with spaces turned into hyphens. This gives you a clickable TOC that survives any tool, and you control the wording and order exactly. It's the safest choice when you're not sure whether your converter supports automatic generation.

Tip: If a heading has punctuation, the slug usually drops it — ## Step 1: Setup typically becomes #step-1-setup. If a link doesn't jump, open the rendered output, check the actual id the tool assigned, and match it.

Converting to PDF with the TOC intact

Once your TOC exists (generated or hand-built), you need a converter that preserves internal anchor links so the entries stay clickable in the PDF. Paste your Markdown into ConvertMDapp, confirm the TOC links jump to the right sections in the live preview, and click Export PDF. The headings keep their anchors, so your contents list stays clickable in the exported file — and because it runs in your browser, nothing is uploaded.

For very long documents, also consider a hard page break after the TOC so the body starts on a fresh page:

<div style="page-break-after: always"></div>

Which method should you use?

If you already use Pandoc, use its flag. If you want a TOC that works no matter what converts the file, build the list by hand — it's a few minutes and never breaks.

FAQ

How do I make the table of contents clickable in the PDF? Ensure each heading has an id (most tools add these automatically) and that your TOC entries link to #heading-id. Then convert with a tool that preserves internal anchor links, and the entries stay clickable.

Can I add a table of contents without Pandoc? Yes. Write the TOC yourself as a Markdown list of links pointing to #heading-slug anchors. This works in any converter, including browser-based ones.

Why does my PDF show the literal text [TOC]? Your converter doesn't recognize that marker. Either use a tool that supports it (like VS Code's Markdown All in One), or replace [TOC] with a hand-written list of anchor links. See the full Markdown-to-PDF guide for more.