# 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:

```bash
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:

```bash
# 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:

```bash
pandoc --version
```

```text
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](https://github.com/jgm/pandoc/releases/latest). 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](https://github.com/jgm/pandoc/releases/latest), or use a package manager:

    ```bash
    choco install pandoc
    ```

    ```bash
    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](https://github.com/jgm/pandoc/releases/latest), or use Homebrew or MacPorts:

    ```bash
    brew install pandoc
    ```

    ```bash
    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](https://github.com/jgm/pandoc/releases/latest) and install:

    ```bash
    sudo dpkg -i pandoc-*.deb
    ```

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

    ```bash
    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:

    ```bash
    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.

```bash
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:

| Platform | Recommended TeX |
|----------|-----------------|
| Windows  | [MiKTeX](https://miktex.org/) |
| macOS    | [BasicTeX](https://www.tug.org/mactex/morepackages.html) or [TinyTeX](https://yihui.org/tinytex/) |
| Linux    | [TeX Live](https://www.tug.org/texlive/) (`apt-get install texlive`) |

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:

```text
            +---------+        +-------------------+        +---------+
  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:

| Option | Long form | Purpose |
|--------|-----------|---------|
| `-f` / `-r` | `--from=` / `--read=` | Input (source) format |
| `-t` / `-w` | `--to=` / `--write=` | Output (target) format |
| `-o` | `--output=` | Write to a file instead of the screen |
| `-s` | `--standalone` | Produce a complete document, not a fragment |

```bash
# 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:

```bash
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:

```bash
# 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:

```bash
pandoc --list-extensions=gfm
```

```text
+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:

```bash
echo "# Hello" | pandoc -t html
```

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

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

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

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

```bash
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:

```bash
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:

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
# 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:

```yaml
---
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

```bash
# 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
```

| Option | Long form | Affects |
|--------|-----------|---------|
| `-M` | `--metadata=KEY[:VAL]` | Document metadata **and** template variables; escaped into templates |
| `-V` | `--variable=KEY[=VAL]` | Template variables only |
| `--metadata-file=` | | Reads metadata from a YAML/JSON file |

> [!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

```bash
# 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:

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

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

```bash
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:

```bash
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`:

| Intermediate (`-t`) | Default engine | Other valid engines |
|---------------------|----------------|---------------------|
| `latex` (default)   | `pdflatex`     | `xelatex`, `lualatex`, `tectonic`, `latexmk` |
| `context`           | `context`      | — |
| `html`              | `weasyprint`   | `prince`, `wkhtmltopdf`, `pagedjs-cli` |
| `ms`                | `groff`        | `pdfroff` |
| `typst`             | `typst`        | — |

```bash
# 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`:

```bash
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:

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

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

```lua
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:

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

This is exactly equivalent to:

```bash
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`](https://github.com/jgm/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:

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

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

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

Control the citation style with a [CSL](https://citationstyles.org) stylesheet:

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

| Option | Purpose |
|--------|---------|
| `-C` / `--citeproc` | Process citations and build a bibliography |
| `--bibliography=FILE` | Bibliography source (`.bib`, `.json`, `.yaml`, `.ris`…); repeatable; URLs allowed |
| `--csl=FILE` | Citation Style Language stylesheet (default: `chicago-author-date`) |
| `--citation-abbreviations=FILE` | Journal-title abbreviations file |

> [!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:

| Option | Result |
|--------|--------|
| (default) | TeX rendered to Unicode where possible; wrapped in `<span class="math">` |
| `--mathjax[=URL]` | Render with [MathJax](https://www.mathjax.org); CDN used if no URL given |
| `--katex[=URL]` | Render with [KaTeX](https://katex.org) |
| `--mathml` | Convert to MathML (native in browsers; default for ODT) |
| `--webtex[=URL]` | Convert formulas to `<img>` tags via an external rendering service |
| `--gladtex` | Wrap math in `<eq>` tags for the GladTeX post-processor |

```bash
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:

| Format | Technology |
|--------|------------|
| `revealjs` | reveal.js (HTML5 + JavaScript) |
| `slidy`, `slideous`, `s5`, `dzslides` | Other HTML/JavaScript slide systems |
| `beamer` | LaTeX Beamer (compiles to PDF) |
| `pptx` | Microsoft PowerPoint |

```bash
# 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 (`---`).

```bash
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`:

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

```bash
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:

```bash
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`:

```bash
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

| Command | What it shows |
|---------|---------------|
| `pandoc --version` | Version, enabled features, user data directory |
| `pandoc --list-input-formats` | All readable formats |
| `pandoc --list-output-formats` | All writable formats |
| `pandoc --list-extensions[=FORMAT]` | Extensions and their default state |
| `pandoc --list-highlight-languages` | Languages available for code highlighting |
| `pandoc --list-highlight-styles` | Available syntax-highlighting styles |
| `pandoc -D FORMAT` | Default template for a format |
| `pandoc --print-default-data-file=FILE` | A bundled data file (e.g. `reference.docx`) |

For verbose tracing while you debug a conversion:

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

To make warnings fatal (useful in CI):

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

To capture machine-readable logs:

```bash
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:

| Code | Meaning |
|------|---------|
| 1 | IO error (`PandocIOError`) |
| 3 | Warnings present with `--fail-if-warnings` |
| 4 | Application error |
| 5 | Template error |
| 6 | Option error |
| 21 | Unknown reader |
| 22 | Unknown writer |
| 23 | Unsupported extension |
| 24 | Citeproc error |
| 31 | EPUB subdirectory error |
| 43 | PDF error |
| 47 | PDF program not found |
| 61 | HTTP error |
| 64 | Parse error |
| 66 | Make-PDF error |
| 83 | Filter error |
| 84 | Lua error |
| 92 | UTF-8 decoding error |
| 99 | Resource not found |

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

| Option | Purpose |
|--------|---------|
| `-f`, `--from=FORMAT` | Input format |
| `-t`, `--to=FORMAT` | Output format |
| `-o`, `--output=FILE` | Write to FILE (`-` for the screen) |
| `-s`, `--standalone` | Full document, not a fragment |
| `--toc`, `--toc-depth=N` | Table of contents (needs `-s`) |
| `-N`, `--number-sections` | Number headings |
| `-M KEY:VAL`, `--metadata` | Set document metadata |
| `-V KEY=VAL`, `--variable` | Set a template variable |
| `--template=FILE` | Custom template |
| `--embed-resources` | Inline images/scripts/styles into HTML |
| `--extract-media=DIR` | Pull media out of docx/odt/epub |
| `--reference-doc=FILE` | Style reference for docx/odt/pptx |
| `--pdf-engine=PROGRAM` | Choose the PDF engine |
| `-L`, `--lua-filter=SCRIPT` | Apply a Lua filter |
| `-F`, `--filter=PROGRAM` | Apply a JSON filter |
| `-C`, `--citeproc` | Process citations |
| `--bibliography=FILE`, `--csl=FILE` | Bibliography source and style |
| `--mathjax`, `--katex`, `--mathml` | Math rendering in HTML |
| `-i`, `--incremental` | Incremental list reveal in slides |
| `--slide-level=N` | Heading level that starts a slide |
| `-d`, `--defaults=FILE` | Load a defaults file |
| `--sandbox` | Restrict IO for untrusted input |
| `--verbose`, `--quiet`, `--trace` | Verbosity controls |

---

_Generated June 2026 from jgm/pandoc at 9376458. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._