Pandoc Cheatsheet

What is Pandoc

"Pandoc is a free-software document converter, widely used as a writing tool (especially by scholars) and as a basis for publishing workflows. It was created by John MacFarlane, a philosophy professor at the University of California, Berkeley. Pandoc dubs itself a "markup format" converter. It can take a document in one of the supported formats and convert only its markup to another format. Maintaining the look and feel of the document is not a priority."

Wikipedia page for Pandoc

Useful Pandoc Commands

Basic conversion with custom fonts:

pandoc --pdf-engine=xelatex -V "mainfont:Inter" -V "monofont:IBM Plex Mono" README.md -o README.pdf

Conversion with line spacing and disabled hyphenation:

pandoc A10\ -\ Sucre\ Noir.md -o A10.pdf --pdf-engine=xelatex -V "mainfont:Inter" -V "monofont:Fragment Mono" -V linestretch=1.15 -V header-includes="\usepackage{ragged2e}\RaggedRight\tolerance=1000\emergencystretch=0em\hyphenpenalty=10000\exhyphenpenalty=10000"

Minimal conversion using the default settings:

pandoc A11\ -\ Enquête\ sur\ la\ faculté\ d\'entendement.md -o A11.pdf --pdf-engine=xelatex

YAML Headers

YAML headers let you define document metadata and settings at the top of a Markdown file. Pandoc reads them automatically during conversion:

---
title: "Here is the title"
author: "Here are the authors"
date: 17/12/2025
papersize: a4
geometry: margin=1in
mainfont: "Helvetica Neue"
toc: true
lang: fr-FR
---

Equations

Pandoc supports LaTeX equations natively. In some cases (InDesign layout, for example) it can be useful to convert equations from LaTeX to SVG. The following website allows you to do this: latex2image.joeraut.com

`mdpdf` — Markdown to PDF Shortcut

Instead of typing the full pandoc command each time, add this function to your ~/.zshrc:

mdpdf() {
  if [[ $# -ne 1 ]]; then
    echo "Usage: mdpdf path/to/file.md" >&2
    return 1
  fi

  local input="$1"

  if [[ ! -f "$input" ]]; then
    echo "Error: file not found: $input" >&2
    return 1
  fi

  local output="${input:r}.pdf"

  pandoc "$input" \
    --pdf-engine=xelatex \
    -V papersize:a4 \
    -V geometry:margin=2.2cm \
    -o "$output"
}

Then reload your shell:

source ~/.zshrc

Usage:

mdpdf path/to/file.md

The output PDF is saved alongside the source file with the same name. The function validates that exactly one argument is given and that the file exists before running, so errors surface clearly instead of producing a cryptic pandoc message.

Order Footnotes Script

When writing in Markdown, footnote numbers can become inconsistent as you add, remove, or reorder them. This Python script takes a Markdown file as input and rewrites all footnote numbers to match their order of appearance in the text.

Usage:

python3 order-footnotes.py file.md

#!/usr/bin/env python3
import sys
import re
from pathlib import Path

def main():
    if len(sys.argv) != 2:
        print("Usage: python3 order-footnotes.py file.md")
        sys.exit(1)

    path = Path(sys.argv[1])
    if not path.exists():
        print(f"Error: file not found: {path}")
        sys.exit(1)

    text = path.read_text(encoding="utf-8")

    ref_pattern = re.compile(r'\[\^([^\]]+)\]')
    def_pattern = re.compile(r'^\[\^([^\]]+)\]:\s*(.*)$', re.MULTILINE)

    definitions = {fid: content for fid, content in def_pattern.findall(text)}

    mapping = {}
    reverse_map = {}
    next_num = 1

    def replace_ref(match):
        nonlocal next_num
        old_id = match.group(1)
        if old_id not in mapping:
            mapping[old_id] = next_num
            reverse_map[next_num] = old_id
            next_num += 1
        return f"[^{mapping[old_id]}]"

    new_text = ref_pattern.sub(replace_ref, text)

    new_defs = []
    for new_id in range(1, next_num):
        old_id = reverse_map[new_id]
        if old_id in definitions:
            new_defs.append(f"[^{new_id}]: {definitions[old_id]}")
        else:
            new_defs.append(f"[^{new_id}]: ")

    new_text = def_pattern.sub("", new_text).rstrip() + "\n\n" + "\n".join(new_defs) + "\n"

    path.write_text(new_text, encoding="utf-8")
    print(f"Footnotes reordered in: {path}")

if __name__ == "__main__":
    main()

Pandoc Plugin for Obsidian

About the installation and the dependencies of the plugin, see here.

A common issue is that the settings page will display the red error message Pandoc is not installed or accessible on your PATH. This plugin's functionality will be limited. If you encounter this issue:

Open the plugin settings and scroll to the bottom
There is a setting called Pandoc path. Set this setting to:
1. Mac/Linux: the output of which pandoc in a terminal
2. Windows: the output of Get-Command pandoc in PowerShell

Pandoc cheatsheet