CheatSheetsHero

Browse / Pandoc Document Conversion Cheatsheet

April 26, 2025 20:02
cli
document-conversion
markdown
pandoc
Download PDF
Missing something?

Pandoc Document Conversion Cheatsheet

A quick reference guide for Pandoc, the universal document converter. Covers basic syntax, common options, markdown extensions, and useful tips for converting documents between various formats.

Core Usage & Basics

Basic Conversion Syntax

Convert Markdown to HTML:

 
pandoc input.md -o output.html

Convert HTML to Markdown:

 
pandoc input.html -o output.md

Convert Markdown to PDF (requires LaTeX):

 
pandoc input.md -o output.pdf

Convert Markdown to DOCX:

 
pandoc input.md -o output.docx

Specify input and output formats explicitly:

 
pandoc -f markdown -t html input.txt -o output.html

Convert from stdin to stdout:

 
echo '# Hello' | pandoc

Convert multiple input files:

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

Convert from a URL:

 
pandoc -o page.html https://www.example.com/page.html

Basic Metadata & Options

--standalone, -s

Produce a standalone document (with header and footer).

Example:

pandoc -s input.md -o output.html

--metadata KEY=VALUE

Add metadata. Can be used multiple times.

Example:

pandoc -s --metadata title="My Document" --metadata author="Me" input.md -o output.html

--metadata-file FILE

Read metadata from a YAML file.

Example:

pandoc -s --metadata-file meta.yaml input.md -o output.html

meta.yaml:

title: Another Doc
author: [Author One, Author Two]

--toc, --table-of-contents

Include an automatically generated table of contents.

Example:

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

--number-sections

Number section headings in the output.

Example:

pandoc --number-sections input.md -o output.html

--variable KEY=VALUE

Set template variables. Useful for customizing output templates.

Example:

pandoc -s --variable lang=en input.md -o output.html

--css FILE

Link to a CSS file in HTML output.

Example:

pandoc -s --css style.css input.md -o output.html

Input/Output Formats (-f, -t)

Common Input Formats (-f)

markdown (default)
commonmark
gfm (GitHub Flavored Markdown)
latex
html
docx
odt
rst (reStructuredText)
mediawiki
json

Common Output Formats (-t)

html (default)
html5
latex
beamer (LaTeX slides)
docx
odt
epub
pdf (requires LaTeX or other engine)
markdown
gfm
rst
mediawiki
json
plain

List all supported formats:

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

Use format extensions (e.g., -f markdown+footnotes)

Extensions enable/disable specific features. Use pandoc --list-extensions [FORMAT] to see options.

Example:

pandoc -f markdown+smart --toc input.md -o output.html

Convert to HTML with specific extensions:

 
pandoc -f markdown -t html+smart+footnotes input.md -o output.html

Convert to PDF using xelatex engine:

 
pandoc input.md -o output.pdf --pdf-engine=xelatex

Convert to DOCX with a reference document:

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

(Template DOCX controls styles)

Convert to HTML using a custom template:

 
pandoc -s --template my-template.html input.md -o output.html

(Templates control the overall document structure)

Markdown Extensions & Content

Tables

Pipe Tables: Simple syntax, requires header and separator line. Align with colons.

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

Pipe Table Alignment:

| Left    | Right   | Center |
|:--------|--------:|:------:|
| Aligned | Aligned | Aligned|

Simple Tables: More flexible, no pipes needed. Requires blank lines before and after.

Header 1  Header 2
--------  --------
Cell 1    Cell 2
Cell 3    Cell 4

Simple Table Alignment: Determined by the colon placement in the separator line.

Left      Right     Center
:-------- --------:  :------:
Aligned   Aligned   Aligned

Grid Tables: Full features (multi-line cells, row/col spans). More complex.

+---------------+---------------+--------------------
| Header        | Header        | Header             |
+===============+===============+====================
| Primary block | Secondary     | Third              |
|               | block         | column             |
+---------------+---------------+--------------------
|               |               |                    |
+---------------+---------------+--------------------

Enable grid tables explicitly if needed:

pandoc -f markdown+grid_tables input.md -o output.html

Compact tables (for simple 2-column data):

Item 1
  Description 1

Item 2
  Description 2

Code Blocks & Highlighting

Fenced Code Blocks: Use triple backticks or tildes. Add language identifier for highlighting.

```python
def hello():
    print("Hello, world!")
```

Indented Code Blocks: Indent lines by 4 spaces or 1 tab. No language highlighting.

    def hello():
        print("Hello, world!")

Inline Code: Use single backticks.

This is `inline code`.

Syntax Highlighting:
By default, Pandoc tries to guess the language or uses the identifier. Uses highlighting-kate package.

Example (with language):

print('Hello')

Example (no language):

This won't be highlighted.

Disable highlighting:

pandoc --no-highlight input.md -o output.html

List available highlighting styles:

pandoc --list-highlight-styles

Apply a specific highlighting style:

pandoc --highlight-style tango input.md -o output.html

Create a custom highlighting style (usually requires dumping default style and editing).

Lists & Definition Lists

Bulleted Lists: Use -, +, or * followed by a space.

- Item one
+ Item two
  - Sub-item
* Item three

Ordered Lists: Use numbers followed by a period or parenthesis.

1. First item
2. Second item
   a. Sub-item A
   b. Sub-item B
#. Third item (automatic numbering)

Definition Lists: Term on a line, definition indented on the next line(s).

Term 1
  Definition of term 1.

Term 2
  Definition of term 2, continued on next line.

Another Term
  : Definition with colon

Pandoc supports various list markers (e.g., (i), A., I)). It tries to follow the initial marker style.

Lists can contain multiple paragraphs, code blocks, etc., by indenting everything belonging to the list item.

Example of list with multiple blocks:

-   First item.

    Second paragraph of first item.

    ```python
    # Code block in list item
    ```

-   Second item.

Ensure blank lines between list items if they contain multiple paragraphs or blocks.

Images, Links, & Footnotes

Inline Images: ![Alt text](URL "Optional title")

![Pandoc Logo](pandoc-logo.png "The Pandoc logo")

Reference Images: ![Alt text][label] then [label]: URL "Optional title"

![Pandoc Logo][logo]

[logo]: pandoc-logo.png "The Pandoc logo"

Inline Links: [Link text](URL "Optional title")

Visit the [Pandoc website](https://pandoc.org "Pandoc Homepage").

Reference Links: [Link text][label] then [label]: URL "Optional title"

Visit the [Pandoc website][pandoc-url].

[pandoc-url]: https://pandoc.org "Pandoc Homepage"

Automatic Links: URLs in angle brackets <URL> or email addresses.

<https://pandoc.org>
<[email protected]>

Footnotes: Place [^label] where you want the reference, then define the footnote anywhere else.

This is my point.[^1]

[^1]: This is the footnote content.

Another point.[^longnote]

[^longnote]: This is a longer footnote.
    It can contain multiple paragraphs.

Use [^#] for automatically numbered footnotes.

First footnote.[^#]
Second footnote.[^#]

Advanced Features & Tips

Citations and Bibliography

Pandoc can automatically generate citations and a bibliography from various formats (BibTeX, CSL-JSON, etc.) using a Citation Style Language (CSL) file.

Required options:
--citeproc: Enables the citation processor.
--bibliography FILE: Specify the bibliography file.
--csl FILE: Specify the CSL style file (e.g., apa.csl).

Example:

pandoc --citeproc --bibliography myrefs.bib --csl chicago-author-date.csl input.md -o output.html

Place citations using keys from your bibliography file, enclosed in square brackets and prefixed with @.

Example Markdown:

This is a point [@smith2004].

Multiple citations [@smith2004; @jones2006].

Narrative citation: Smith says [@smith2004, p. 33].

The bibliography will be inserted automatically at the end of the document where a section titled “Bibliography” or “References” (or similar) is found, or appended if no such section exists.

Common bibliography formats:
.bib (BibTeX)
.json (CSL-JSON)
.yaml (CSL-YAML)

Find CSL styles:
Download from the CSL repository.

Using a .bib file:

@article{smith2004,
  title={Article Title},
  author={Smith, John},
  journal={Journal Name},
  year={2004}
}

Filters (Lua)

Filters are programs that can read the pandoc Abstract Syntax Tree (AST) in JSON format, modify it, and write it back out. Lua filters are powerful and easy to use.

Use the --lua-filter FILE option.

Example:

pandoc --lua-filter myfilter.lua input.md -o output.html

A simple Lua filter to change all emphasis (*text*) to strong (**text**):

-- myfilter.lua
function Emph(elem)
  return Strong(elem.c)
end

Filters can inspect and modify any element in the AST (paragraphs, headings, links, images, etc.).

Multiple filters can be applied by listing them sequentially:

pandoc --lua-filter filter1.lua --lua-filter filter2.lua input.md -o output.html

Explore the Pandoc documentation for the full AST structure and examples of more complex filters.

Filters are useful for:

  • Custom AST transformations
  • Adding features not built-in
  • Processing specific attributes (e.g., on Divs or Spans)

Useful Tips & Tricks

Debug AST:

Convert to JSON format to inspect the intermediate representation:

pandoc input.md -t json

Get default template:

Dump the default template for a specific format to customize it:

pandoc -D html5 > my-template.html

Include raw content (e.g., LaTeX in Markdown):

Use raw attribute blocks.

```{=latex}
\usepackage{fancyhdr}
\pagestyle{fancy}

<script>alert('Hello!');</script>

Convert directory of files:

Use shell scripting to process multiple files.

for f in *.md; do pandoc "$f" -o "${f%.md}.html"; done

Processing front-matter:

Pandoc reads YAML metadata blocks at the start of the document.

---
title: My Title
author: John Doe
---

# Start of content
...

Convert Markdown to PDF with custom margins (using LaTeX variables):

 
pandoc input.md -o output.pdf \
  -V geometry:margin=1in \
  --pdf-engine=pdflatex

Using includes:

Include headers, before/after body content in LaTeX/PDF output.

--include-in-header=header.tex
--include-before-body=before.tex
--include-after-body=after.tex

Adding classes/IDs to elements:

Use curly braces {} with #id or .class.

# My Heading {#custom-id .main-title}

Paragraph text. {.intro}

Troubleshooting & Help

Check Pandoc version:

 
pandoc --version

Get help on options:

 
pandoc --help
pandoc -h

Check for required dependencies (e.g., LaTeX for PDF, citeproc for citations, highlighting-kate for highlighting).

Common PDF issues often stem from missing LaTeX packages. Pandoc usually tells you which one is missing.

Complex conversions or template issues can often be debugged by converting to the intermediate JSON AST (-t json) to see how Pandoc parsed the input.

Consult the official Pandoc User’s Guide online for the most comprehensive information and advanced features.