MD2PDF OnlineMD Converter
← Back to Blog

How to Add a Table of Contents to Markdown PDF (3 Methods)

Long Markdown documents need navigation. A table of contents (TOC) helps readers jump to sections and understand the document structure at a glance.

Here are 3 methods to add a TOC when converting Markdown to PDF.

Method 1: Pandoc Automatic TOC (Recommended)

Pandoc can generate a TOC automatically from your heading structure.

Basic TOC

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

This creates a TOC from all headings (#, ##, ###, etc.).

Control TOC Depth

Limit how many heading levels appear:

# Only H1 and H2 headings
pandoc document.md -o document.pdf --toc --toc-depth=2

# H1, H2, H3 headings
pandoc document.md -o document.pdf --toc --toc-depth=3

TOC Options

Option Effect Example
--toc Enable TOC --toc
--toc-depth=N Levels to include (1-6) --toc-depth=3
--toc-title="..." Custom TOC title --toc-title="Contents"

Example Output

A document with:

# Introduction
## Overview
## Goals

# Main Content
## Section A
### Subsection A1
### Subsection A2

# Conclusion

With --toc --toc-depth=2 produces:

Contents
  Introduction
    Overview
    Goals
  Main Content
    Section A
  Conclusion

Best for: Technical documents, long guides, automated workflows.

Pros:

  • Automatic from headings
  • Clickable links in PDF
  • Customizable depth
  • Professional formatting

Cons:

  • Requires Pandoc installation
  • TOC style is fixed (unless using templates)

Method 2: Manual TOC in Markdown

You can create a TOC manually in your Markdown file.

Basic Manual TOC

## Table of Contents

- [Introduction](#introduction)
- [Main Content](#main-content)
  - [Section A](#section-a)
  - [Section B](#section-b)
- [Conclusion](#conclusion)

---

## Introduction
...

## Main Content
...

## Section A
...

How Heading IDs Work

Markdown headings get auto-generated IDs based on the text:

| Heading | Generated ID | |---|---|---| | # Introduction | #introduction | | ## Section A | #section-a | | ## Section A! | #section-a-1 (special chars removed) |

Tools to Generate Manual TOC

Some tools auto-generate the TOC Markdown:

  • VS Code extensions: "Markdown All in One" can generate TOC
  • Online tools: Various TOC generators
  • Scripts: Custom script to parse headings

Best for: Documents you edit frequently, control over TOC order.

Pros:

  • Works with any converter
  • Full control over TOC content
  • Can reorder or exclude sections

Cons:

  • Manual maintenance
  • Must update when headings change
  • No automation

Method 3: Online Converter with TOC

Some online Markdown-to-PDF converters can generate a TOC.

Using MD2PDF Online

  1. Go to MD2PDF Online
  2. Paste or upload your Markdown
  3. Enable TOC option (if available)
  4. Preview the result
  5. Export to PDF

When Online TOC Works Best

MD2PDF processes your Markdown and can generate clickable heading links. For a full TOC page:

  1. Add a manual TOC section to your Markdown
  2. Use the live preview to verify links work
  3. Export the PDF

Best for: Quick documents, users without Pandoc, one-time conversions.

Pros:

  • No installation
  • Works on any device
  • Live preview shows TOC before export

Cons:

  • May need manual TOC in Markdown
  • Less customization than Pandoc

Comparison Table

Feature Pandoc TOC Manual TOC Online Converter
Automatic ✅ ❌ Varies
Customizable depth ✅ ✅ Limited
Clickable links ✅ ✅ ✅
Maintenance None Manual Varies
Setup Install Pandoc None None
Styling control Full Markdown only Limited

Advanced Pandoc TOC Styling

For professional documents, use a custom template:

LaTeX Template

# Use XeLaTeX with custom TOC styling
pandoc document.md -o document.pdf \
  --toc \
  --toc-depth=3 \
  --pdf-engine=xelatex \
  -V toc-title="Table of Contents" \
  -V geometry:margin=1in

Custom CSS for HTML-then-PDF

# Generate HTML first with TOC
pandoc document.md -o document.html --toc --standalone

# Apply custom CSS
# Then convert HTML to PDF with browser or wkhtmltopdf

When to Use Each Method

| Document Type | Recommended Method | |---|---|---| | Technical guide (many sections) | Pandoc --toc --toc-depth=3 | | Short article (3-5 headings) | Manual TOC or none | | Blog post | None usually needed | | Book or thesis | Pandoc with LaTeX template | | Quick one-time export | MD2PDF with manual TOC |

Example: Complete Document with TOC

Markdown file:

# User Guide

## Introduction
Welcome to our product.

## Getting Started
### Installation
### Configuration

## Features
### Core Features
### Advanced Features

## Troubleshooting
Common issues and solutions.

## Conclusion
Thank you for reading.

Pandoc command:

pandoc user-guide.md -o user-guide.pdf \
  --toc \
  --toc-depth=3 \
  --toc-title="Contents" \
  --pdf-engine=xelatex

Result: A professional PDF with:

  • Title page (User Guide)
  • TOC showing all H2 and H3 headings
  • Clickable links to each section
  • Clean typography

Frequently Asked Questions

Does the TOC include clickable links?

Yes, in all methods:

  • Pandoc: Links work automatically
  • Manual: [Section](#section) creates clickable links
  • Online: Most converters preserve links

Can I put the TOC at the end instead of the beginning?

Not easily with Pandoc's automatic TOC. Workarounds:

  1. Create a manual TOC and place it at the end
  2. Use a custom Pandoc Lua filter to move TOC
  3. Generate PDF, then rearrange pages with a PDF tool

How do I exclude some headings from the TOC?

With Pandoc --toc-depth, you control levels. To exclude specific headings:

  1. Use a different heading level (e.g., H4 for non-TOC sections)
  2. Or use --toc-depth=2 and make excluded sections H3

Can I style the TOC differently?

With Pandoc + LaTeX templates, yes. You can customize:

  • Font size
  • Spacing
  • Indentation
  • Title styling

For basic conversions, TOC styling is determined by the converter's defaults.

What if my headings have special characters?

Pandoc and Markdown converters normalize heading IDs:

  • ## Section A & B → #section-a-b
  • ## What's New? → #whats-new

Manual TOC links must match these normalized IDs.

Try it now: For quick TOC-enabled PDFs, add a manual TOC to your Markdown and convert at MD2PDF Online. For automated TOCs on long documents, use Pandoc with --toc.