Markdown to Word with Table of Contents: Auto-Generate TOC Guide

Why Add a TOC to Your Markdown Documents?

A table of contents is far more than a cosmetic addition. For any document longer than a few pages, it serves as the primary navigation tool your reader will rely on. In printed documents, the TOC provides page numbers. In digital Word files, it creates clickable hyperlinks that jump directly to the relevant section. Without a TOC, readers are forced to scroll through dozens or hundreds of pages to find what they need -- a frustrating experience that undermines even the best-written content.

Beyond navigation, a TOC signals professionalism. When you hand a document to a manager, a client, or an academic committee, the presence of a table of contents tells them that the author has taken the time to organize and structure the material properly. It conveys attention to detail and a commitment to quality. Documents without a TOC can feel unfinished or amateurish, regardless of how strong the actual content is.

Many institutions and organizations explicitly require a table of contents. Universities mandate them in theses and dissertations. Government agencies require them in grant proposals and regulatory filings. Corporate style guides often specify a TOC for any document exceeding a certain page count. If your document will be reviewed by any of these entities, including a TOC is not optional -- it is a hard requirement for submission.

Markdown Heading Hierarchy

The foundation of any table of contents is a well-structured heading hierarchy. In Markdown, headings are defined with the hash symbol (#), and the number of hashes determines the heading level. A single hash creates an H1, two hashes create an H2, and so on up to H6. When you convert Markdown to Word, these heading levels map directly to Word's built-in heading styles (Heading 1, Heading 2, Heading 3, etc.), which is exactly what Word's TOC generator uses to build the table of contents.

# Document Title                -> Heading 1 (H1)
## Chapter or Major Section     -> Heading 2 (H2)
### Subsection                  -> Heading 3 (H3)
#### Sub-subsection             -> Heading 4 (H4)
##### Minor Heading             -> Heading 5 (H5)
###### Lowest Level             -> Heading 6 (H6)

For most documents, you will use H1 through H3 or H4. Using all six levels is rare and usually indicates that the document structure is overly nested. A typical report or paper uses H1 for the title, H2 for major sections, and H3 for subsections within those sections. Technical documentation may extend to H4 for detailed sub-subsections.

Common Mistakes to Avoid

Heading hierarchy errors are the single most common reason that auto-generated tables of contents look wrong. Here are the mistakes that cause problems:

Method 1: Pandoc --toc Flag

Pandoc is the gold standard for Markdown-to-Word conversion, and it has built-in support for generating a table of contents. The --toc flag (short for "table of contents") tells Pandoc to insert a TOC at the beginning of the output document, built automatically from the heading structure of your Markdown file. This is the most reliable method because Pandoc understands the heading hierarchy natively and generates proper Word field codes.

Basic Command

The simplest Pandoc command to convert a Markdown file to Word with a table of contents:

pandoc input.md -o output.docx --toc

This single command reads your Markdown file, converts it to a Word document, and inserts a table of contents at the very beginning. The TOC will include all headings from H1 through H3 by default, with each entry linked to the corresponding section in the document.

Controlling TOC Depth with --toc-depth

By default, Pandoc includes headings down to level 3 (H1, H2, H3) in the TOC. You can change this with the --toc-depth flag. Set it to any value from 1 to 6:

# Only include H1 and H2 in the TOC (high-level overview)
pandoc input.md -o output.docx --toc --toc-depth=2

# Include H1 through H4 (detailed TOC for technical docs)
pandoc input.md -o output.docx --toc --toc-depth=4

# Only top-level headings (executive summary style)
pandoc input.md -o output.docx --toc --toc-depth=1

# Maximum depth (all heading levels)
pandoc input.md -o output.docx --toc --toc-depth=6

Setting TOC Title

By default, Pandoc labels the TOC section "Table of Contents" in the output. You can customize this title using a YAML metadata block at the top of your Markdown file:

---
title: "My Project Report"
toc-title: "Contents"
---

# Introduction
...

# Background
...

The toc-title metadata field changes the heading text above the TOC. This is useful when your organization uses a different label (such as "Contents", "Outline", or a non-English equivalent).

Combining with a Reference Document

For fully professional output, combine the TOC flag with a reference document that controls styling:

pandoc input.md -o output.docx --toc --toc-depth=3 --reference-doc=template.docx

The reference document (template.docx) defines the fonts, sizes, colors, and spacing for every element in the output -- including the TOC entries. This means you can create a branded template once and reuse it for every conversion, ensuring consistent formatting across all your documents.

Method 2: Online Converter with TOC

Not everyone has Pandoc installed, and not everyone is comfortable with the command line. Online Markdown-to-Word converters provide a browser-based alternative that requires zero setup. Our tool at markdown-to-word.online supports table of contents generation as part of the conversion process, making it accessible to anyone with a web browser.

How It Works

The online converter is ideal for one-off conversions, for users who are not familiar with command-line tools, and for situations where you need a quick result without configuring Pandoc or installing dependencies. For repeated or batch conversions, Pandoc remains the more powerful option because of its extensive customization flags.

Method 3: Manual TOC in Word

If you have already converted your Markdown to Word without a TOC, you can add one directly in Microsoft Word. This approach works because Pandoc (and most other converters) map Markdown headings to Word's built-in Heading 1, Heading 2, and Heading 3 styles. Word's TOC generator uses these styles to build the table of contents, so the heading structure from your Markdown is already in place.

Step-by-Step Instructions

This method has the advantage of giving you full control over the TOC appearance within Word's familiar interface. You can choose from several built-in designs, adjust the number of levels shown, toggle page numbers on or off, and switch between dotted and solid tab leaders. The downside is that it adds a manual step to your workflow -- every time you reconvert from Markdown, you will need to re-insert the TOC in Word.

Customizing TOC Appearance

A default TOC works fine for most purposes, but professional documents often require specific formatting. The TOC font, indentation, spacing, page number alignment, and leader dots (the dotted line connecting entries to page numbers) all need to match your organization's style guide. There are two main approaches to customization: styling through Pandoc's reference document, and manual formatting in Word.

Using a Pandoc Reference Document

The most efficient way to customize the TOC appearance is to create a reference document (template) with pre-configured TOC styles. Here is how to set it up:

pandoc -o custom-reference.docx --print-default-data-file reference.docx

pandoc input.md -o output.docx --toc --reference-doc=custom-reference.docx

Key TOC Styles to Customize

Page Numbers and Tab Leaders

When you insert a TOC in Word (either via Pandoc or manually), page numbers are aligned to the right margin by default, connected to the entry text by dotted tab leaders. You can customize this in Word by going to References > Table of Contents > Custom Table of Contents and adjusting the "Tab leader" dropdown. Options include dots (......), dashes (------), a solid line, or no leader at all. Dots are the most widely used convention and are appropriate for nearly all professional contexts.

Advanced: Multi-Level TOC with Numbering

Many professional and academic documents require numbered headings (1, 1.1, 1.1.1, etc.) that appear in the table of contents. Pandoc supports this through the --number-sections flag, which automatically adds hierarchical numbering to all headings in the output.

# Generate Word with numbered sections and TOC
pandoc input.md -o output.docx --toc --number-sections

# Combine with TOC depth control
pandoc input.md -o output.docx --toc --toc-depth=3 --number-sections

# Full professional setup: numbered sections + TOC + custom template
pandoc input.md -o output.docx --toc --toc-depth=3 --number-sections --reference-doc=template.docx

With --number-sections enabled, your Markdown headings are automatically transformed in the output:

Markdown Input:              Word Output:
# Introduction           ->  1 Introduction
## Background            ->  1.1 Background
## Objectives            ->  1.2 Objectives
### Primary Goals        ->  1.2.1 Primary Goals
# Methodology            ->  2 Methodology
## Data Collection       ->  2.1 Data Collection
## Analysis              ->  2.2 Analysis

The TOC will reflect these numbers, producing entries like "1 Introduction......1", "1.1 Background......3", and so on. This numbered format is standard for technical reports, government documents, ISO standards, and many academic theses. It makes cross-referencing easier because you can refer to "Section 2.3" instead of a heading title.

Custom Numbering Schemes

If your organization uses a non-standard numbering scheme (such as Roman numerals for top-level sections, or letter-based numbering like A, B, C), Pandoc's default --number-sections will not produce the right format. In that case, you have two options: add the numbering manually in your Markdown headings (e.g., ## A. First Section) and omit the --number-sections flag, or convert with standard numbering and then adjust the numbering format in Word using multi-level list settings. For most users, the default Arabic numeral scheme (1, 1.1, 1.1.1) will be correct.

Excluding Specific Headings from Numbering

Some headings -- like "Acknowledgments", "References", or "Appendix" -- should not be numbered. In Pandoc, you can exclude a heading from section numbering by adding the .unnumbered class:

# Acknowledgments {.unnumbered}

Thank you to everyone who contributed to this project.

# References {.unnumbered}

- Smith, J. (2025). *Markdown in Practice*.

These headings will still appear in the TOC but without a section number, which is exactly the convention expected in most academic and professional documents.

Keeping TOC Updated

A table of contents in Word is a "field" -- a dynamic element that can be refreshed to reflect changes in the document. If you edit the Word document after conversion (adding sections, renaming headings, or changing page layouts), the TOC will not automatically update. You need to explicitly tell Word to recalculate it.

How to Update the TOC

Understanding Word Field Codes

Behind the scenes, Word's table of contents is powered by the TOC field code. You can view this by pressing Alt+F9, which toggles between the rendered TOC and the underlying field code. A typical TOC field looks like this:

{ TOC \o "1-3" \h \z \u }

The switches control the TOC behavior: \o "1-3" specifies heading levels 1 through 3, \h creates hyperlinks, \z hides tab leaders in web layout view, and \u uses paragraph outline levels. You can manually edit these switches for fine-grained control, but for most users, the graphical interface in References > Table of Contents is sufficient.

Frequently Asked Questions