Pandoc User Guide

Pandoc is the universal document converter: a single command-line tool that reads a document written in one markup or word-processing format and writes it out in another. It converts from roughly fifty input formats — including many flavors of Markdown, HTML, LaTeX, Word .docx, reStructuredText, Org mode, EPUB, Jupyter notebooks, and several bibliography formats — to even more output formats, including HTML, PDF, LaTeX, Word, PowerPoint, EPUB, slide shows, man pages, and dozens of wiki and lightweight-markup formats.

This guide shows you how to install pandoc, run conversions, and use its most powerful features: templates, filters, citations, math, and slide shows. It is written for people who run pandoc from a terminal. For architecture, deployment, and internals, see the companion Admin Guide.

Note

Pandoc is both a command-line program and a Haskell library. This guide covers the command-line tool. Throughout, the program is invoked as pandoc.

1. Quick Start

Pandoc reads from files (or standard input) and writes to a file (or standard output). The most basic conversion looks like this:

pandoc -o output.html input.txt

This reads input.txt (assumed to be Markdown) and writes output.html (HTML). Pandoc guesses both formats from the file extensions.

Tip

Pandoc guesses the input format from the input file extension and the output format from the output file extension. When output goes to the screen and the extension is unknown, the output format defaults to HTML; when input comes from standard input with an unknown extension, the input format defaults to Markdown.

Try these one-liners once pandoc is installed:

# Markdown file to a Word document
pandoc notes.md -o notes.docx

# Markdown to a standalone HTML page (with <head>/<body>)
pandoc -s notes.md -o notes.html

# Markdown to PDF (requires a PDF engine such as LaTeX — see section 8)
pandoc notes.md -o notes.pdf

# Convert a Word document to Markdown
pandoc report.docx -o report.md

# Convert and print to the terminal (no output file)
pandoc -t plain notes.md

To verify your installation and see configuration details:

pandoc --version

pandoc 3.10
Features: +server +lua
Scripting engine: Lua 5.4
User data directory: /home/you/.local/share/pandoc
...

2. Installation

The simplest way to get the latest release is the official installer from the pandoc releases page. Platform-specific package managers are also supported.

Important

Using more than one installation method can leave you with two separate pandoc installations. Uninstall the old one before switching methods.

2.1 Install by platform

Windows

Run the MSI installer from the download page, or use a package manager:

choco install pandoc

winget install --source winget --exact --id JohnMacFarlane.Pandoc

A zip file containing just the binaries and documentation is also provided if you prefer not to use the installer.

macOS

Run the package installer from the download page, or use Homebrew or MacPorts:

brew install pandoc

port install pandoc

Linux

Pandoc is in the Debian, Ubuntu, Slackware, Arch, Fedora, NixOS, openSUSE, gentoo, and Void repositories. To get the latest release, download the .deb or tarball from the download page and install:

sudo dpkg -i pandoc-*.deb

Or unpack the statically-linked tarball into a prefix such as /usr/local:

tar xvzf pandoc-*-linux-amd64.tar.gz --strip-components 1 -C /usr/local

Conda

Conda Forge provides a statically-linked build that works across platforms:

conda install -c conda-forge pandoc

Warning

The statically-linked binaries provided by the pandoc project (and Conda Forge) cannot use Lua filters that depend on Lua modules written in C. If you need those, install through a method that links dynamically, or compile from source.

2.2 Run pandoc with Docker

The official pandoc/core image contains pandoc; pandoc/latex adds the minimal LaTeX needed to produce PDFs.

docker run --rm --volume "`pwd`:/data" --user `id -u`:`id -g` \
  pandoc/latex README.md -o README.pdf

2.3 A note on PDF output

PDF generation is not built into pandoc — it shells out to an external engine. By default pandoc uses LaTeX, so installing a TeX distribution is the most common prerequisite:

You can choose a non-LaTeX engine with --pdf-engine; see section 8.

3. How Pandoc Works

Understanding pandoc's model makes everything else easier. Pandoc has a modular, reader → AST → writer design:

            +---------+        +-------------------+        +---------+
  input --> | READER  | -----> |  Pandoc AST       | -----> | WRITER  | --> output
 (markdown) | (parse) |        | (abstract syntax  |        | (render)|    (e.g. html)
            +---------+        |  tree of the doc) |        +---------+
                               +-------------------+
                                        ^
                                        |
                                  FILTERS modify
                                  the AST in between

A reader parses your input into a single internal representation — the Pandoc abstract syntax tree (AST). A writer renders that AST into the target format. Adding a new format means adding only a reader or a writer; every format can convert to every other through the shared AST.

Note

Because the AST is intentionally simpler than many of the formats it bridges, conversions are not always loss-free. Pandoc preserves structural elements (headings, lists, tables, emphasis) but not fine formatting details like margins. Converting from a format richer than pandoc's Markdown (for example, a complex .docx) can be lossy.

This is also why filters (section 9) are so useful: they let you transform the document at the AST stage, after parsing and before rendering, in a way that works regardless of input or output format.

4. Specifying Input and Output Formats

You can name formats explicitly instead of relying on extension guessing:

# Convert hello.txt from Markdown to LaTeX
pandoc -f markdown -t latex hello.txt

# Convert a web page's HTML to Markdown
pandoc -f html -t markdown hello.html

To see every format your build supports:

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

4.1 Input formats

Pandoc can read (among others): markdown, commonmark, commonmark_x, gfm, markdown_mmd, markdown_phpextra, markdown_strict, html, latex, docx, odt, epub, rst, org, textile, mediawiki, dokuwiki, jira, twiki, tikiwiki, vimwiki, creole, muse, man, mdoc, pod, haddock, docbook, jats, bits, fb2, ipynb, typst, djot, t2t, csv, tsv, xlsx, native, json, and several bibliography formats (bibtex, biblatex, csljson, ris, endnotexml).

4.2 Output formats

Pandoc can write (among others): html/html5, html4, chunkedhtml, latex, beamer, context, pdf, docx, odt, rtf, epub/epub3, epub2, fb2, icml, markdown and its variants, gfm, commonmark, djot, rst, org, textile, mediawiki, dokuwiki, xwiki, zimwiki, jira, asciidoc, man, ms, texinfo, vimdoc, markua, docbook/docbook5, jats_archiving/jats_publishing/jats_articleauthoring, tei, opml, opendocument, pptx, several BBCode flavors, plain, ansi, native, json, and the slide-show formats revealjs, slidy, slideous, dzslides, s5.

Note

odt, docx, epub, and pdf output is binary. Pandoc will not send it to the screen unless you force it with -o -.

4.3 Format extensions

Most formats accept extensions that turn individual features on or off. Append +EXTENSION to enable or -EXTENSION to disable:

# GitHub-Flavored Markdown without the default emoji extension
pandoc -f gfm-emoji input.md -o out.html

# Pandoc Markdown plus hard line breaks in output
pandoc -t markdown+hard_line_breaks input.md

List the extensions available for a format:

pandoc --list-extensions=gfm

+all_symbols_escapable
-angle_brackets_escapable
+ascii_identifiers
+autolink_bare_uris
...

5. Everyday Conversions

This section collects the most common real-world tasks as copy-paste recipes.

5.1 Reading from standard input and the web

With no input file, pandoc reads from standard input:

echo "# Hello" | pandoc -t html

<h1 id="hello">Hello</h1>

Give an absolute URL instead of a file and pandoc fetches it over HTTP:

pandoc -f html -t markdown https://www.fsf.org

You can attach custom request headers (for example a user agent):

pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
  https://www.fsf.org

5.2 Combining multiple files

List several input files and pandoc concatenates them (with a blank line between each) before parsing:

pandoc chapter1.md chapter2.md chapter3.md -s -o book.html

Tip

Use --file-scope to parse each file independently. This keeps footnotes with the same identifier in different files from colliding. Reading binary inputs (docx, odt, epub) implies --file-scope automatically.

5.3 Producing a standalone document

By default pandoc emits a fragment — just the body content. Add -s/--standalone to wrap it in a full document with the appropriate header and footer:

pandoc -s notes.md -o notes.html

Note

Standalone mode is turned on automatically for pdf, epub, docx, odt, and fb2 output, because those formats are inherently complete documents.

5.4 Table of contents and section numbers

pandoc -s --toc --toc-depth=2 -N manual.md -o manual.html

• --toc (or --table-of-contents) inserts an automatically generated table of contents. It requires -s.
• --toc-depth=NUMBER controls how many heading levels appear (default 3).
• -N/--number-sections numbers headings (in LaTeX, ConTeXt, HTML, Docx, ms, and EPUB).

5.5 Self-contained HTML

To produce a single HTML file with images, scripts, and stylesheets inlined as data: URIs:

pandoc -s --embed-resources notes.md -o standalone.html

Note

--embed-resources replaces the older --self-contained, which is now a deprecated synonym for --embed-resources --standalone.

5.6 Extracting media from a document

When reading a .docx, .epub, or .odt, pull out the embedded images:

pandoc report.docx --extract-media=./media -o report.md

Images are written into ./media and the references in the output are rewritten to point at them. End the path in .zip to get a zip archive instead of a directory.

5.7 Styling a Word or ODT document

Pandoc uses a reference document to control the styles of docx/odt output. Generate a starting point, edit its styles, then reuse it:

# 1. Get the default reference doc
pandoc -o custom-reference.docx --print-default-data-file reference.docx

# 2. Open custom-reference.docx in Word, edit the styles, save.

# 3. Use it for future conversions
pandoc report.md --reference-doc=custom-reference.docx -o report.docx

Tip

Only modify the styles in the reference document (Heading 1–9, Body Text, Source Code, Block Text, etc.) — its actual content is ignored. The same workflow applies to reference.odt for ODT and reference.pptx for PowerPoint.

6. Working with Markdown

Pandoc's Markdown is an enriched dialect with first-class syntax for tables, definition lists, footnotes, math, metadata, and citations. A few essentials:

6.1 Metadata blocks

Put a YAML block at the top of a Markdown file to set the title, author, date, and template variables:

---
title: My Report
author: Jane Doe
date: 2026-06-04
---

These fields populate the document title in standalone output and are available to templates and filters.

6.2 Setting metadata and variables on the command line

# Set document metadata (affects the document and templates)
pandoc -M title="Quarterly Report" report.md -s -o report.html

# Set a template variable (affects only rendering in standalone mode)
pandoc -V lang=en -V fontsize=12pt report.md -s -o report.pdf

Note

If you supply -V author=Joe -V author=Sue, pandoc collects the repeated values into a list rather than overwriting. To assign structured values (lists, maps) directly, use --variable-json or a defaults file.

6.3 Heading levels

# Demote every heading by one level (level 2 -> level 1, etc.)
pandoc --shift-heading-level-by=-1 input.md -o output.md

This is handy when a source document uses a level-1 heading as its title; --shift-heading-level-by=-1 promotes that title into document metadata.

7. Templates and Variables

A template is the skeleton pandoc fills in when producing standalone output. Each output format has a built-in default template, but you can supply your own.

Inspect the default template for any format:

pandoc -D html5
pandoc --print-default-template=latex -o my-template.latex

Use a custom template (this implies --standalone):

pandoc report.md --template=mytemplate.html -s -o report.html

Tip

If --template is given a bare name with no extension, pandoc looks in the templates subdirectory of your user data directory and appends the writer's extension — so --template=letter finds letter.html for HTML output.

Variables referenced in a template are set with -V/--variable or through metadata. For example, the LaTeX template understands variables like geometry, fontsize, mainfont, and linestretch.

8. Creating PDFs

To make a PDF, just give an output file with a .pdf extension:

pandoc report.md -o report.pdf

Behind the scenes pandoc converts to an intermediate format (LaTeX by default) and runs an external engine. Choose a different engine — and intermediate path — with --pdf-engine:

# Use XeLaTeX (good for custom fonts / Unicode)
pandoc report.md --pdf-engine=xelatex -V mainfont="DejaVu Serif" -o report.pdf

# Generate the PDF from HTML/CSS instead of LaTeX
pandoc report.md -t html --pdf-engine=weasyprint -c style.css -o report.pdf

Tip

To debug a PDF, output the intermediate file instead and inspect it: pandoc -s report.md -o report.tex, then run pdflatex report.tex yourself to see the real error.

Pass extra flags to the engine with --pdf-engine-opt:

pandoc report.md --pdf-engine=latexmk --pdf-engine-opt=-outdir=build -o report.pdf

Warning

The error pdflatex not found. Please select a different --pdf-engine or install pdflatex (exit code 47) means no PDF engine is installed. Install a TeX distribution (section 2.3) or choose an engine you already have.

9. Filters: Transforming the Document

Filters run on the AST, between reading and writing, so a single filter works for any input/output combination. Pandoc supports two kinds.

9.1 Lua filters (built in)

Lua filters need no external interpreter — the engine is compiled into pandoc:

pandoc input.md --lua-filter=uppercase-headers.lua -o output.html

A minimal Lua filter that turns every level-1 heading into uppercase:

function Header(el)
  if el.level == 1 then
    return pandoc.walk_block(el, {
      Str = function(s) return pandoc.Str(s.text:upper()) end
    })
  end
end

9.2 JSON filters (any language)

A JSON filter is any executable that reads the AST as JSON on standard input and writes the modified AST as JSON on standard output:

pandoc input.md --filter=./caps.py -t latex

This is exactly equivalent to:

pandoc -t json input.md | ./caps.py latex | pandoc -f json -t latex

The target format name is passed to the filter as its first argument. Filters can be written in any language; Python users often use the pandocfilters module.

Note

Filters, Lua filters, and citation processing (--citeproc) are applied in the order they appear on the command line. Order matters when filters depend on each other.

Pandoc searches for filters in (1) the given path, (2) the filters subdirectory of the user data directory, and (3) your $PATH.

10. Citations and Bibliographies

Pandoc has a built-in citation processor (citeproc). Turn it on with -C/--citeproc and supply bibliographic data:

pandoc paper.md --citeproc --bibliography=refs.bib -o paper.pdf

In your document, cite sources with the @key syntax:

As shown by @smith2020, the results are robust [@jones2019; @doe2021].

Control the citation style with a CSL stylesheet:

pandoc paper.md -C --bibliography=refs.bib --csl=ieee.csl -o paper.pdf

Note

--natbib and --biblatex are different: they leave citations untouched and emit LaTeX \cite commands for processing by BibTeX/biber. Do not combine them with --citeproc or with direct PDF output.

11. Math Rendering in HTML

When writing HTML, choose how TeX math is displayed:

pandoc -s --mathjax math.md -o math.html

12. Slide Shows

Pandoc turns a Markdown document into presentation slides. Each output format below is a different slide system:

# A reveal.js slide deck
pandoc -t revealjs -s slides.md -o slides.html

# A PowerPoint deck
pandoc slides.md -o slides.pptx

# A Beamer PDF
pandoc -t beamer slides.md -o slides.pdf

Useful slide options:

• -i/--incremental — reveal list items one at a time.
• --slide-level=NUMBER — set which heading level starts a new slide (0–6). A value of 0 means slides break only on horizontal rules (---).

pandoc -t revealjs -i --slide-level=2 -s slides.md -o slides.html

13. Reusable Option Sets: Defaults Files

Instead of typing long command lines, store options in a YAML defaults file and load it with -d/--defaults:

# letter.yaml
from: markdown
to: pdf
pdf-engine: xelatex
standalone: true
toc: true
variables:
  geometry: margin=1in
  fontsize: 11pt
metadata:
  author: Jane Doe

pandoc report.md --defaults=letter.yaml -o report.pdf

Almost every command-line option has a defaults-file equivalent. Command-line options given alongside --defaults override or extend the file. Place defaults files in the defaults subdirectory of your user data directory to invoke them from anywhere by name:

pandoc report.md -dletter -o report.pdf

Tip

In defaults-file path fields you can interpolate environment variables (${HOME}), the user data directory (${USERDATA}), and the defaults file's own directory (${.}).

14. Security: Handling Untrusted Input

If you run pandoc on documents from people you do not trust, use --sandbox:

pandoc --sandbox untrusted.md -o out.html

Sandbox mode limits the IO that readers and writers can perform to the files named on the command line, protecting against tricks such as disclosing local files through include directives.

Caution

--sandbox does not restrict IO performed by filters or by the external PDF engine. When generating PDFs from user-controlled HTML, server-side request forgery is possible through the underlying engine — review your engine's network settings and treat remote resource fetching as a risk. Anyone processing untrusted input should combine --sandbox with a binary compiled with embed_data_files so that data-file lookups still succeed inside the sandbox.

15. Useful Diagnostic Commands

For verbose tracing while you debug a conversion:

pandoc --verbose --trace input.md -o output.html

To make warnings fatal (useful in CI):

pandoc --fail-if-warnings input.md -o output.html

To capture machine-readable logs:

pandoc --log=conversion.json input.md -o output.html

16. Troubleshooting

Conversions fail with a nonzero exit code and a message on standard error. Match the message below to a fix.

Error: pdflatex not found. Please select a different --pdf-engine or install pdflatex

Cause: PDF output was requested but no LaTeX engine is installed (exit code 47, PandocPDFProgramNotFoundError). Solution: Install a TeX distribution (MiKTeX, BasicTeX, or TeX Live — section 2.3), or pick an engine you have with --pdf-engine (for example --pdf-engine=weasyprint with -t html). Prevention: Run pandoc --version and confirm a working engine before scripting PDF jobs.

Error: Unknown reader: FORMAT / Unknown writer: FORMAT

Cause: A format name passed to -f/-t is misspelled or unsupported (exit codes 21/22). Solution: Check the exact spelling against pandoc --list-input-formats / --list-output-formats. Format names are lowercase (gfm, docx, revealjs). Prevention: Remember that extensions attach to the format with +/-, e.g. markdown+emoji, not as separate words.

Error: Unknown extension: NAME

Cause: An extension appended with +/- is not valid for that format (exit code 23). Solution: Run pandoc --list-extensions=FORMAT to see valid extensions for the format you are using.

Error: File not found in resource path

Cause: Pandoc could not locate an image or other resource while producing PDF/docx output (exit code 99). Solution: Add the directory holding the resource with --resource-path. Remember to include the working directory explicitly: --resource-path=.:images. Prevention: Keep image paths relative to where you run pandoc, or set --resource-path in a defaults file.

Error: PDF build fails with a LaTeX error you cannot read

Cause: The LaTeX engine rejected the generated .tex (exit code 43 or 66). Solution: Re-run with -s -o output.tex to capture the intermediate LaTeX, then compile it manually with pdflatex output.tex to see the real LaTeX error. Missing packages are the usual cause; install them via your TeX package manager (e.g. tlmgr install <package>).

Problem: Output is just a fragment, missing <head>/<body> or a title

Cause: Standalone mode was not enabled. Solution: Add -s/--standalone. Note that --toc, --css, and --include-in-header have no visible effect without it.

Problem: Math looks wrong or unstyled in HTML

Cause: No math renderer was selected, so complex formulas fall back to Unicode. Solution: Add --mathjax or --katex (section 11). For self-contained files, be aware that dynamically loaded MathJax fonts cannot be embedded by --embed-resources.

Problem: Converting Word "Track Changes" produces unexpected text

Cause: By default pandoc accepts tracked insertions and deletions. Solution: Use --track-changes=reject to drop them, or --track-changes=all to keep them as marked spans for scripting.

Problem: A character-encoding error on input

Cause: Input is not UTF-8 (exit code 92, PandocUTF8DecodingError). Solution: Pandoc requires UTF-8. Convert first with iconv: iconv -t utf-8 input.txt | pandoc | iconv -f utf-8.

17. Exit Codes

Pandoc returns 0 on success. Common nonzero codes:

The full list is available in the manual; use these for scripting and CI checks.

18. FAQ

Q: Which input format does pandoc assume if I don't specify one? If the input file extension is unknown, or input comes from standard input, pandoc assumes Markdown.

Q: Which output format is the default? If output goes to the screen (or the output file extension is unknown), pandoc defaults to HTML.

Q: Can I convert directly between any two formats? Yes — every reader connects to every writer through the shared AST. Quality varies: converting from a format richer than pandoc's Markdown can be lossy.

Q: How do I make a PDF without installing LaTeX? Use an HTML-based engine: pandoc input.md -t html --pdf-engine=weasyprint -o out.pdf. WeasyPrint, Prince, wkhtmltopdf, and pagedjs-cli all work from HTML/CSS.

Q: How do I embed everything into one HTML file? Use pandoc -s --embed-resources input.md -o out.html. Images, scripts, and styles are inlined as data: URIs.

Q: How do I keep pandoc from reaching out to the network or the filesystem on untrusted input? Use --sandbox. Note it does not constrain filters or the PDF engine (section 14).

Q: How do I reuse a long set of options? Put them in a YAML defaults file and load it with -d/--defaults (section 13).

Q: Where does pandoc look for templates, reference docs, filters, and CSL files? In your user data directory. Find it with pandoc --version. You can override it per run with --data-dir.

Q: How do I see which extensions are on by default for my format? pandoc --list-extensions=FORMAT. A + prefix means enabled by default, - means disabled.

Q: Can pandoc read directly from a URL? Yes — give an absolute URL in place of an input file and pandoc fetches it over HTTP.

Q: How do I split a long document into chapters for EPUB or chunked HTML? Use --split-level=NUMBER to choose the heading level at which to split (default is level 1).

Q: My code blocks aren't highlighted. Why? Highlighting is on by default for many formats but needs a recognized language class on the code block. Check available languages with --list-highlight-languages, and pick a style with --syntax-highlighting=STYLE.

19. Reference: Most-Used Options at a Glance