pandoc.org

What is Pandoc?

Pandoc is a free, open-source command-line tool that converts documents between formats — the site calls it "a universal document converter." You give it a file in one markup language and it writes out the same content in another, preserving structure like headings, lists, tables, footnotes and citations wherever the target format supports them.

Its main draw is breadth. A single tool covers writing, publishing and data workflows that would otherwise need several separate converters.

What it converts between

• Lightweight markup: Markdown (including CommonMark and GitHub-flavored), reStructuredText, AsciiDoc, Org-Mode, Textile, djot
• Word processor and office files: Microsoft Word docx, RTF, OpenOffice/LibreOffice ODT
• Ebooks: EPUB 2 and 3, FictionBook2
• Web and XML: HTML4/HTML5, chunked HTML, DocBook, JATS, TEI, OpenDocument XML
• Academic and technical: LaTeX, ConTeXt, BibTeX/BibLaTeX, CSL JSON/YAML, Jupyter notebooks
• Slide shows: PowerPoint, LaTeX Beamer, reveal.js, Slidy, S5
• Data and serialization: CSV/TSV tables, Excel spreadsheets, JSON and XML representations of its internal document model
• PDF, produced indirectly through engines such as pdflatex, xelatex, wkhtmltopdf, weasyprint or context

Who tends to use it

Writers who keep drafts in Markdown but must submit Word files; researchers moving between LaTeX and journal XML formats; developers generating documentation, slide decks or static sites from plain text; and anyone converting ebook or wiki content in bulk.

Trade-offs to know

Pandoc is a converter, not a word processor — there is no editing interface, and styling is controlled by templates rather than by hand. Because formats differ in what they can express, complex layout, tracked changes or heavily designed Word documents may not survive a round trip intact. It also runs from the terminal, so non-technical users often rely on an editor or build script that calls it.

A practical next step

Pick the pair of formats you actually need — for example, Markdown to docx for a manuscript submission — and test one real file before committing to a workflow. Check whether your target format is listed as a full conversion (↔) or one-way (→), since one-way formats limit how far you can round-trip. If you would rather not work in a terminal, editors and publishing tools such as Obsidian and static-site generators can drive Pandoc behind the scenes.

How do I install Pandoc on my system?

Install Pandoc by choosing the method that matches how you already manage software on your machine. The official site is Pandoc, and its installation guidance is the source of truth for current options.

Common installation routes

• Windows: Use the MSI installer from the Pandoc releases page, or install via a package manager if you use one (for example Chocolatey or winget). The MSI is the simplest path for a single machine.
• macOS: Use the Homebrew formula (brew install pandoc) or download the macOS package. Homebrew makes upgrades easy.
• Linux: Prefer your distribution's package manager (apt, dnf, pacman, etc.) for a system-wide install. Many distributions ship a recent-enough version; if you need the newest features, use the standalone .deb/.rpm or a static binary.
• Cross-platform / no admin rights: Download a standalone binary or use a container image. This is useful on shared or locked-down systems.
• Via another language ecosystem: If you already work in Python, R, or Node, wrapper packages can install a bundled Pandoc for you, though the version may lag behind the official release.

A practical decision rule

If you want the latest format support—for example newer Markdown extensions or additional writers—install from the official release rather than an old distro package. If you value automatic updates and system integration, use your package manager.

Verify and try it

After installing, confirm it works and see the supported formats:

pandoc --version
pandoc --list-input-formats
pandoc --list-output-formats

Then convert a file to test the setup:

pandoc input.md -o output.docx

That single command shows why Pandoc is often described as a universal document converter: one tool moves content between Markdown, Word, HTML, LaTeX, EPUB and many other formats. If the version check fails, the binary is not on your PATH—reopen your terminal or add the install directory manually.

Can Pandoc convert a Markdown file to a Word document with a custom reference template?

Yes. Pandoc converts Markdown to Microsoft Word .docx, and its reference-document mechanism is exactly how you apply a custom template. You supply a .docx file whose styles (fonts, colors, heading styles, margins, headers/footers, etc.) Pandoc reuses when generating the output.

How it works in practice

Pandoc ships with a default reference document. You can generate it, edit it in Word, then pass it back on the command line:

pandoc --print-default-data-file reference.docx > custom-reference.docx
# edit custom-reference.docx in Word, save it
pandoc input.md --reference-doc=custom-reference.docx -o output.docx

Anything defined as a named style in the reference document — Heading 1 through Heading 6, Body Text, Block Text, Table, Source Code, and so on — carries over to the generated file. Pandoc maps its own logical elements to those style names, so the practical workflow is: rename or restyle the existing styles rather than inventing new ones.

What carries over and what does not

The last row is the common surprise: people put a TOC field in the reference document and expect it to populate. Instead, use --toc and style the resulting entries.

A concrete scenario

A consultancy needs every client report to match a corporate Word template. They create reference.docx with the firm's heading fonts, a footer with page numbers, and a table style. Writers author in Markdown, then run one command per report. The output opens in Word already branded, and because the reference document is version-controlled, the styling stays consistent across the team.

Decision criteria

• Use --reference-doc when you need corporate styling, specific fonts, or print-ready page setup.
• Skip it if default Word styling is acceptable — plain pandoc input.md -o output.docx works fine.
• If you need finer control than styles allow, Pandoc supports custom writers in Lua, and its filter system can post-process the document tree before it is written.

For the full list of supported input and output formats, plus the reference-document documentation, see Pandoc.

How do I use Pandoc to create a PDF with LaTeX math and a table of contents?

Use Pandoc's Markdown-to-PDF path with a table-of-contents flag and let a LaTeX engine handle the math. The essential command is:

pandoc input.md -o output.pdf --toc --number-sections --pdf-engine=xelatex

Pandoc reads Markdown (including CommonMark and GitHub-flavored variants), and when the output is PDF it delegates typesetting to a LaTeX-based engine such as pdflatex, lualatex, xelatex, latexmk, tectonic, or a non-LaTeX route like wkhtmltopdf or weasyprint. For math-heavy documents, a LaTeX engine is usually the right choice because it renders formulas natively rather than approximating them.

What each part does

• input.md is your source; write math inline as $...$ or as display math with $$...$$. Pandoc understands LaTeX math and even macros in Markdown, so you can define \newcommand and reuse it.
• --toc inserts a table of contents. Add --toc-depth=2 if you only want top-level and second-level headings.
• --number-sections numbers the headings and, by default, the TOC entries, which is common for reports and theses.
• --pdf-engine=xelatex selects the engine. Use xelatex or lualatex when you need Unicode fonts or custom font setup; pdflatex is fine for standard Latin text.

A concrete scenario

Suppose you are writing a technical report with equations and want a clean PDF for a supervisor. Keep the source in Markdown, add a YAML metadata block at the top for title and author, and run the command above. If the math is complex, prefer lualatex or xelatex; if you need a specific document class, pass it with --template or a custom LaTeX header via -H header.tex.

Trade-offs

• LaTeX engines give the best math and typography but require a working TeX installation; tectonic can fetch packages on demand but needs network access the first time.
• HTML-based PDF engines avoid TeX but may not render LaTeX math as reliably, so they suit simpler documents.
• --toc works across output formats, so the same source can produce HTML, EPUB, or DOCX with a TOC.

If you want to test quickly, convert to HTML first with --mathjax to check the math visually, then switch to PDF. For broader format conversions, see Pandoc.

What are the limitations of Pandoc when converting complex Word documents with tracked changes?

Pandoc is a format converter, not a Word document repair tool. Its strength is converting structured text between markup formats; tracked changes are a Word-specific revision layer that does not map cleanly onto most other formats, so that is where conversions tend to break down.

Practical limitations with tracked changes

• Pandoc generally does not carry revision marks (insertions, deletions, comments, formatting changes) through to the output. In many cases the accepted text is what ends up in the converted file, and the revision history is lost.
• Deletions can behave unpredictably: text that is marked as deleted may be dropped, retained, or appear without any indication it was ever a deletion, depending on the document and output format.
• Comments and annotations typically do not survive conversion, since most target formats have no equivalent structure.
• Complex Word features that often accompany revision-heavy documents — nested tables, text boxes, content controls, headers/footers, footnotes with unusual numbering, and custom styles — are a common source of layout drift or lost content.
• Round-tripping is risky. Converting docx to Markdown and back to docx will not reproduce the original document, and any revision state is gone after the first pass.

How to work around it

Resolve revisions in Word first: accept or reject all changes, delete or export comments, and simplify unusual layout elements. Then convert. If you need an auditable trail, save a copy of the original with revisions intact before flattening it for conversion.

The underlying issue is structural, not a bug: revision tracking is an editorial layer, while Pandoc's model is a document tree of content and semantic markup. If preserving the change history matters, keep the Word file as the system of record and use Pandoc only for producing a clean downstream version.

When Pandoc is still a good fit

If your goal is to move the final, agreed-upon text into Markdown, HTML, LaTeX, EPUB, or a wiki format, Pandoc handles that well — including metadata, footnotes, tables, and math. For a broader look at what it converts, see Pandoc. For the Word side of the workflow, Microsoft's own documentation on reviewing and accepting tracked changes is the right place to start: Microsoft Support.

A useful decision rule: if the tracked changes are part of what you need to keep, do not route the file through Pandoc. If they are just noise on the way to a clean export, resolve them in Word and then convert.

Is Pandoc free and open-source, and can I use it for commercial projects?

Yes. Pandoc is free and open-source software, and you can use it for commercial work. The project distributes it under the GPL, which permits commercial use, modification and redistribution. The practical condition is that if you redistribute a modified version (or bundle it into something you ship), you generally must release that derivative under the same license and make the source available. Running Pandoc internally to convert your own documents—client deliverables, internal reports, ebooks you sell—does not trigger that obligation.

What that means by scenario

If you only ever call Pandoc from a script or pipeline, the copyleft applies to Pandoc, not to your script.

A useful next step

Read the license text that ships with the version you download, since the exact obligations depend on which license that release uses. Then check whether your use is "internal tool" or "redistributed component"—that single distinction decides almost everything.

For broader context on document conversion alternatives, see LibreOffice and John MacFarlane.