Pandoc Markdown to Word: The Complete Guide

Pandoc is a free, open-source universal document converter created by John MacFarlane, a philosophy professor at the University of California, Berkeley. Often described as the "Swiss Army knife" of document conversion, Pandoc can convert files between dozens of markup formats, including Markdown, HTML, LaTeX, Microsoft Word (DOCX), EPUB, PDF, and many more.

What makes Pandoc the most powerful tool for converting Markdown to Word? Unlike simple online converters that only handle basic formatting, Pandoc provides granular control over every aspect of the output. You can apply custom Word templates (reference documents), generate tables of contents, handle citations with BibTeX, render mathematical equations, apply syntax-highlighted code blocks, and much more — all from the command line.

Pandoc is written in Haskell and runs on Windows, macOS, and Linux. It is actively maintained and has a vibrant community with hundreds of contributors. Whether you are a developer writing technical documentation, an academic preparing research papers, or a writer drafting a book manuscript, Pandoc gives you the control and flexibility that no GUI tool can match.

The Essential Command

pandoc input.md -o output.docx

Specifying Formats Explicitly

You can also specify input and output formats explicitly using -f (from) and -t (to) flags:

pandoc -f markdown -t docx -o output.docx input.md

This is useful when your files don't have standard extensions or when you want to use a specific Markdown variant such as markdown_strict, gfm (GitHub Flavored Markdown), or commonmark.

--toc — Table of Contents

Automatically generates a table of contents at the beginning of the document based on your heading structure. You can control the depth with --toc-depth.

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

This generates a TOC that includes headings up to level 3 (H1, H2, H3). The default depth is 3 if --toc-depth is omitted.

--reference-doc — Custom Word Template

Apply a custom Word template to control fonts, colors, spacing, and styles in the output document. This is the most powerful way to brand your documents.

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

To create a reference template, first generate a default one with pandoc -o custom-reference.docx --print-default-data-file reference.docx, then open it in Word and modify the styles (Heading 1, Heading 2, Body Text, etc.) to match your branding.

--filter — Custom Filters

Filters transform the document's AST (Abstract Syntax Tree) between parsing and writing, enabling powerful customizations such as cross-references, diagram rendering, and more.

# Using pandoc-crossref for figure/table numbering
pandoc input.md -o output.docx --filter pandoc-crossref

# Using a Lua filter (no external dependency needed)
pandoc input.md -o output.docx --lua-filter my-filter.lua

Lua filters are recommended for most use cases as they ship with Pandoc and don't require installing additional software. Popular filters include pandoc-crossref and pandoc-citeproc.

--metadata — Document Metadata

Set document metadata such as title, author, and date from the command line. These values populate the Word document's built-in properties and can appear on a title page.

pandoc input.md -o output.docx \
  --metadata title="My Report" \
  --metadata author="Jane Smith" \
  --metadata date="2026-03-18"

You can also define metadata in a YAML front-matter block at the top of your Markdown file, which is often more convenient for documents with rich metadata.