Pandoc Universal Document Converter Skill

Convert documents between 40+ formats with Pandoc. This skill covers Markdown to PDF/DOCX/HTML conversions, custom templates, citation management, and batch processing automation.

When to Use This Skill

USE When

• Converting Markdown to PDF with professional formatting

• Creating Word documents from Markdown sources

• Need reproducible document builds from plain text

• Managing academic papers with citations (BibTeX/CSL)

• Batch converting multiple documents

• Need custom templates for consistent branding

• Converting between multiple documentation formats

• Creating LaTeX documents from Markdown

• Need cross-references (figures, tables, equations)

• Building automated document pipelines

DON'T USE When

• Building documentation websites (use MkDocs or Sphinx)

• Need interactive documentation (use web frameworks)

• Require real-time collaborative editing (use Google Docs)

• Building slide presentations (use Marp)

• Need WYSIWYG editing (use Word directly)

• Converting complex nested HTML (may lose formatting)

Prerequisites

Installation

macOS (Homebrew)

brew install pandoc brew install pandoc-crossref # For cross-references brew install basictex # Minimal LaTeX for PDF

Or full LaTeX: brew install --cask mactex

Ubuntu/Debian

sudo apt-get update sudo apt-get install pandoc pandoc-citeproc sudo apt-get install texlive-xetex texlive-fonts-recommended sudo apt-get install texlive-latex-extra # For additional packages

Fedora/RHEL

sudo dnf install pandoc pandoc-citeproc sudo dnf install texlive-xetex texlive-collection-fontsrecommended

Windows (Chocolatey)

choco install pandoc choco install miktex # LaTeX distribution

Windows (Scoop)

scoop install pandoc scoop install latex

Verify installation

pandoc --version

System Requirements

• Pandoc 2.19 or higher (3.x recommended)

• LaTeX distribution (for PDF output)

• Python 3.8+ (for pandoc-filters)

Core Capabilities

1. Basic Format Conversion

Markdown to PDF

pandoc document.md -o document.pdf

Markdown to DOCX

pandoc document.md -o document.docx

Markdown to HTML

pandoc document.md -o document.html --standalone

Markdown to LaTeX

pandoc document.md -o document.tex

HTML to Markdown

pandoc page.html -o page.md

DOCX to Markdown

pandoc document.docx -o document.md

Multiple input files

pandoc chapter1.md chapter2.md chapter3.md -o book.pdf

Specify input format explicitly

pandoc -f markdown -t pdf document.md -o document.pdf

2. PDF Generation with Options

Basic PDF with table of contents

pandoc document.md -o document.pdf --toc

PDF with XeLaTeX engine (better font support)

pandoc document.md -o document.pdf
--pdf-engine=xelatex
--toc
--toc-depth=3

PDF with custom margins

pandoc document.md -o document.pdf
--pdf-engine=xelatex
-V geometry:margin=1in

PDF with custom fonts

pandoc document.md -o document.pdf
--pdf-engine=xelatex
-V mainfont="Georgia"
-V sansfont="Helvetica"
-V monofont="Menlo"

PDF with paper size and font size

pandoc document.md -o document.pdf
--pdf-engine=xelatex
-V papersize=a4
-V fontsize=11pt

PDF with numbered sections

pandoc document.md -o document.pdf
--number-sections
--toc

PDF with syntax highlighting style

pandoc document.md -o document.pdf
--highlight-style=tango

List available highlighting styles

pandoc --list-highlight-styles

3. Word Document (DOCX) Generation

Basic DOCX

pandoc document.md -o document.docx

DOCX with table of contents

pandoc document.md -o document.docx --toc

DOCX with reference document (template)

pandoc document.md -o document.docx
--reference-doc=template.docx

DOCX with syntax highlighting

pandoc document.md -o document.docx
--highlight-style=kate

Creating a reference document template

pandoc --print-default-data-file reference.docx > template.docx

Edit template.docx in Word to customize styles

4. HTML Generation

Standalone HTML (includes head, body)

pandoc document.md -o document.html --standalone

HTML with custom CSS

pandoc document.md -o document.html
--standalone
--css=styles.css

HTML with embedded CSS

pandoc document.md -o document.html
--standalone
--css=styles.css
--embed-resources
--self-contained

HTML with syntax highlighting

pandoc document.md -o document.html
--standalone
--highlight-style=pygments

HTML with table of contents

pandoc document.md -o document.html
--standalone
--toc
--toc-depth=2

HTML with math rendering (MathJax)

pandoc document.md -o document.html
--standalone
--mathjax

HTML5 output

pandoc document.md -o document.html
--standalone
-t html5

5. Custom LaTeX Templates

%% template.tex - Custom Pandoc LaTeX template \documentclass[$if(fontsize)$$fontsize$,$endif$$if(papersize)$$papersize$paper,$endif$]{article}

%% Packages \usepackage{geometry} \geometry{margin=1in} \usepackage{fontspec} \usepackage{hyperref} \usepackage{fancyhdr} \usepackage{titlesec} \usepackage{xcolor} \usepackage{listings}

%% Fonts $if(mainfont)$ \setmainfont{$mainfont$} $endif$ $if(sansfont)$ \setsansfont{$sansfont$} $endif$ $if(monofont)$ \setmonofont{$monofont$} $endif$

%% Colors \definecolor{linkcolor}{RGB}{0, 102, 204} \definecolor{codebackground}{RGB}{248, 248, 248}

%% Hyperlinks \hypersetup{ colorlinks=true, linkcolor=linkcolor, urlcolor=linkcolor, pdfauthor={$author$}, pdftitle={$title$} }

%% Headers and footers \pagestyle{fancy} \fancyhf{} \fancyhead[L]{$title$} \fancyhead[R]{\thepage} \renewcommand{\headrulewidth}{0.4pt}

%% Code blocks \lstset{ backgroundcolor=\color{codebackground}, basicstyle=\ttfamily\small, breaklines=true, frame=single, numbers=left, numberstyle=\tiny\color{gray} }

%% Section formatting \titleformat{\section} {\Large\bfseries\color{linkcolor}} {\thesection}{1em}{} \titleformat{\subsection} {\large\bfseries} {\thesubsection}{1em}{}

%% Title $if(title)$ \title{$title$} $endif$ $if(author)$ \author{$author$} $endif$ $if(date)$ \date{$date$} $endif$

\begin{document}

$if(title)$ \maketitle $endif$

$if(abstract)$ \begin{abstract} $abstract$ \end{abstract} $endif$

$if(toc)$ \tableofcontents \newpage $endif$

$body$

\end{document}

Use custom template

pandoc document.md -o document.pdf
--template=template.tex
--pdf-engine=xelatex
-V title="My Document"
-V author="Your Name"
-V date="2026-01-17"
--toc

6. YAML Metadata in Documents

title: "Technical Report" author:

• name: "John Smith" affiliation: "University of Example" email: "john@example.edu"
• name: "Jane Doe" affiliation: "Tech Corp" date: "January 17, 2026" abstract: | This document demonstrates advanced Pandoc features including custom metadata, citations, and formatting. keywords:
• documentation
• pandoc
• markdown lang: en-US toc: true toc-depth: 3 numbersections: true geometry: margin=1in fontsize: 11pt mainfont: "Georgia" monofont: "Fira Code" linkcolor: blue bibliography: references.bib csl: ieee.csl

Introduction

Your document content starts here...

7. Citations and Bibliography

%% references.bib @article{smith2024, author = {Smith, John and Doe, Jane}, title = {Advanced Documentation Techniques}, journal = {Journal of Technical Writing}, year = {2024}, volume = {15}, number = {3}, pages = {42--58}, doi = {10.1234/jtw.2024.001} }

@book{johnson2023, author = {Johnson, Robert}, title = {The Complete Guide to Markdown}, publisher = {Tech Press}, year = {2023}, address = {New York}, isbn = {978-0-123456-78-9} }

@inproceedings{williams2025, author = {Williams, Sarah}, title = {Document Automation Best Practices}, booktitle = {Proceedings of DocCon 2025}, year = {2025}, pages = {100--115}, organization = {Documentation Society} }

@online{pandocmanual, author = {{Pandoc Contributors}}, title = {Pandoc User's Guide}, year = {2024}, url = {https://pandoc.org/MANUAL.html}, urldate = {2024-01-15} }

<!-- document.md with citations -->

title: "Research Paper" bibliography: references.bib csl: apa.csl

Literature Review

According to @smith2024, documentation is essential for project success. This aligns with earlier findings [@johnson2023; @williams2025].

The standard approach uses markdown formatting [see @pandocmanual, chapter 3].

Multiple citations can be grouped together [@smith2024; @johnson2023, pp. 15-20].

References

::: {#refs} :::

Generate PDF with citations

pandoc document.md -o document.pdf
--citeproc
--bibliography=references.bib
--csl=apa.csl
--pdf-engine=xelatex

Download CSL styles

https://github.com/citation-style-language/styles

curl -O https://raw.githubusercontent.com/citation-style-language/styles/master/apa.csl curl -O https://raw.githubusercontent.com/citation-style-language/styles/master/ieee.csl curl -O https://raw.githubusercontent.com/citation-style-language/styles/master/chicago-author-date.csl

8. Cross-References with pandoc-crossref

Install pandoc-crossref

macOS

brew install pandoc-crossref

Or download from releases

https://github.com/lierdakil/pandoc-crossref/releases

<!-- document.md with cross-references -->

title: "Document with Cross-References"

Introduction

See @fig:architecture for the system overview. The data flow is described in @sec:dataflow. Results are shown in @tbl:results. The equation @eq:formula describes the relationship.

System Architecture {#sec:architecture}

{#fig:architecture}

Data Flow {#sec:dataflow}

The process follows these steps...

Results

: Performance metrics {#tbl:results}

Mathematical Model

The core formula is:

$$ E = mc^2 $$ {#eq:formula}

Equation @eq:formula shows Einstein's famous equation.

Generate PDF with cross-references

pandoc document.md -o document.pdf
--filter pandoc-crossref
--citeproc
--pdf-engine=xelatex
--number-sections

pandoc-crossref options in YAML

---

figureTitle: "Figure"

tableTitle: "Table"

listingTitle: "Listing"

figPrefix: "Fig."

tblPrefix: "Table"

eqnPrefix: "Eq."

secPrefix: "Section"

---

9. Lua Filters

-- filters/word-count.lua -- Count words in document

local word_count = 0

function Str(el) word_count = word_count + 1 return el end

function Pandoc(doc) print("Word count: " .. word_count) return doc end

-- filters/uppercase-headers.lua -- Convert all headers to uppercase

function Header(el) return pandoc.walk_block(el, { Str = function(s) return pandoc.Str(string.upper(s.text)) end }) end

-- filters/remove-links.lua -- Remove all hyperlinks, keeping text

function Link(el) return el.content end

-- filters/custom-blocks.lua -- Convert custom div blocks to styled output

function Div(el) if el.classes:includes("warning") then -- For LaTeX output local latex_begin = pandoc.RawBlock('latex', '\begin{tcolorbox}[colback=yellow!10,colframe=orange]') local latex_end = pandoc.RawBlock('latex', '\end{tcolorbox}')

    table.insert(el.content, 1, latex_begin)
    table.insert(el.content, latex_end)
    return el.content
end

if el.classes:includes("info") then
    local latex_begin = pandoc.RawBlock('latex',
        '\\begin{tcolorbox}[colback=blue!5,colframe=blue!50]')
    local latex_end = pandoc.RawBlock('latex', '\\end{tcolorbox}')

    table.insert(el.content, 1, latex_begin)
    table.insert(el.content, latex_end)
    return el.content
end

end

-- filters/include-files.lua -- Include content from external files

function CodeBlock(el) if el.classes:includes("include") then local file = io.open(el.text, "r") if file then local content = file:read("*all") file:close()

        -- Get file extension for syntax highlighting
        local ext = el.text:match("%.(%w+)$")
        local lang = ext or ""

        return pandoc.CodeBlock(content, {class = lang})
    end
end

end

Use Lua filters

pandoc document.md -o document.pdf
--lua-filter=filters/uppercase-headers.lua
--lua-filter=filters/custom-blocks.lua

Chain multiple filters

pandoc document.md -o document.pdf
--filter pandoc-crossref
--lua-filter=filters/custom-blocks.lua
--citeproc

10. Batch Conversion Scripts

#!/bin/bash

scripts/batch-convert.sh

Convert all Markdown files to PDF

set -euo pipefail

Configuration

INPUT_DIR="${1:-./docs}" OUTPUT_DIR="${2:-./output}" TEMPLATE="${3:-}"

Create output directory

mkdir -p "$OUTPUT_DIR"

Find and convert all markdown files

find "$INPUT_DIR" -name "*.md" -type f | while read -r file; do # Get relative path and create output path relative="${file#$INPUT_DIR/}" output_file="$OUTPUT_DIR/${relative%.md}.pdf" output_dir=$(dirname "$output_file")

# Create output subdirectory
mkdir -p "$output_dir"

echo "Converting: $file -> $output_file"

# Build pandoc command
cmd=(pandoc "$file" -o "$output_file"
    --pdf-engine=xelatex
    --toc
    --number-sections
    --highlight-style=tango)

# Add template if specified
if [[ -n "$TEMPLATE" ]]; then
    cmd+=(--template="$TEMPLATE")
fi

# Execute conversion
"${cmd[@]}"

done

echo "Batch conversion complete!" echo "Output: $OUTPUT_DIR"

#!/bin/bash

scripts/convert-to-all-formats.sh

Convert a document to multiple formats

set -euo pipefail

INPUT_FILE="${1:?Usage: $0 <input.md>}" BASE_NAME="${INPUT_FILE%.md}"

echo "Converting $INPUT_FILE to multiple formats..."

PDF

echo " -> PDF" pandoc "$INPUT_FILE" -o "${BASE_NAME}.pdf"
--pdf-engine=xelatex
--toc
--number-sections

DOCX

echo " -> DOCX" pandoc "$INPUT_FILE" -o "${BASE_NAME}.docx"
--toc

HTML

echo " -> HTML" pandoc "$INPUT_FILE" -o "${BASE_NAME}.html"
--standalone
--toc
--embed-resources

LaTeX

echo " -> LaTeX" pandoc "$INPUT_FILE" -o "${BASE_NAME}.tex"

EPUB

echo " -> EPUB" pandoc "$INPUT_FILE" -o "${BASE_NAME}.epub"
--toc

echo "Done! Created:" ls -la "${BASE_NAME}".*

#!/usr/bin/env python3 """ scripts/smart_convert.py Smart document converter with configuration file support. """

import subprocess import sys from pathlib import Path import yaml

def load_config(config_path: Path) -> dict: """Load conversion configuration from YAML.""" with open(config_path) as f: return yaml.safe_load(f)

def convert_document( input_file: Path, output_file: Path, config: dict ) -> bool: """Convert a single document using pandoc.""" cmd = ['pandoc', str(input_file), '-o', str(output_file)]

# Add common options
if config.get('toc'):
    cmd.append('--toc')
    if toc_depth := config.get('toc_depth'):
        cmd.extend(['--toc-depth', str(toc_depth)])

if config.get('number_sections'):
    cmd.append('--number-sections')

if template := config.get('template'):
    cmd.extend(['--template', template])

if pdf_engine := config.get('pdf_engine'):
    cmd.extend(['--pdf-engine', pdf_engine])

if highlight := config.get('highlight_style'):
    cmd.extend(['--highlight-style', highlight])

if bibliography := config.get('bibliography'):
    cmd.append('--citeproc')
    cmd.extend(['--bibliography', bibliography])

if csl := config.get('csl'):
    cmd.extend(['--csl', csl])

# Add variables
for key, value in config.get('variables', {}).items():
    cmd.extend(['-V', f'{key}={value}'])

# Add filters
for filter_name in config.get('filters', []):
    if filter_name.endswith('.lua'):
        cmd.extend(['--lua-filter', filter_name])
    else:
        cmd.extend(['--filter', filter_name])

print(f"Running: {' '.join(cmd)}")

result = subprocess.run(cmd, capture_output=True, text=True)

if result.returncode != 0:
    print(f"Error: {result.stderr}", file=sys.stderr)
    return False

return True

def main(): if len(sys.argv) < 3: print(f"Usage: {sys.argv[0]} <input.md> <output.pdf> [config.yaml]") sys.exit(1)

input_file = Path(sys.argv[1])
output_file = Path(sys.argv[2])
config_file = Path(sys.argv[3]) if len(sys.argv) > 3 else None

config = {}
if config_file and config_file.exists():
    config = load_config(config_file)

success = convert_document(input_file, output_file, config)
sys.exit(0 if success else 1)

if name == 'main': main()

config/pandoc-config.yaml

Configuration for smart_convert.py

toc: true toc_depth: 3 number_sections: true pdf_engine: xelatex highlight_style: tango

template: templates/report.tex bibliography: references/main.bib csl: styles/ieee.csl

variables: geometry: margin=1in fontsize: 11pt mainfont: Georgia monofont: Fira Code linkcolor: blue

filters:

• pandoc-crossref
• filters/custom-blocks.lua

11. Makefile for Document Projects

Makefile for document conversion project

Configuration

PANDOC = pandoc PDF_ENGINE = xelatex TEMPLATE = templates/report.tex BIBLIOGRAPHY = references/main.bib CSL = styles/ieee.csl

Directories

SRC_DIR = src OUT_DIR = output BUILD_DIR = build

Source files

MD_FILES := $(wildcard $(SRC_DIR)/*.md) PDF_FILES := $(patsubst $(SRC_DIR)/%.md,$(OUT_DIR)/%.pdf,$(MD_FILES)) DOCX_FILES := $(patsubst $(SRC_DIR)/%.md,$(OUT_DIR)/%.docx,$(MD_FILES)) HTML_FILES := $(patsubst $(SRC_DIR)/%.md,$(OUT_DIR)/%.html,$(MD_FILES))

Common options

PANDOC_OPTS = --toc --number-sections --highlight-style=tango PDF_OPTS = --pdf-engine=$(PDF_ENGINE) --template=$(TEMPLATE) CITE_OPTS = --citeproc --bibliography=$(BIBLIOGRAPHY) --csl=$(CSL)

Phony targets

.PHONY: all pdf docx html clean help

Default target

all: pdf

Build all PDFs

pdf: $(PDF_FILES)

Build all DOCX

docx: $(DOCX_FILES)

Build all HTML

html: $(HTML_FILES)

Pattern rules

$(OUT_DIR)/%.pdf: $(SRC_DIR)/%.md $(TEMPLATE) $(BIBLIOGRAPHY) | $(OUT_DIR) @echo "Building PDF: $@" $(PANDOC) $< -o $@ $(PANDOC_OPTS) $(PDF_OPTS) $(CITE_OPTS)

$(OUT_DIR)/%.docx: $(SRC_DIR)/%.md $(BIBLIOGRAPHY) | $(OUT_DIR) @echo "Building DOCX: $@" $(PANDOC) $< -o $@ $(PANDOC_OPTS) $(CITE_OPTS)

$(OUT_DIR)/%.html: $(SRC_DIR)/%.md $(BIBLIOGRAPHY) | $(OUT_DIR) @echo "Building HTML: $@" $(PANDOC) $< -o $@ --standalone $(PANDOC_OPTS) $(CITE_OPTS) --embed-resources

Create output directory

$(OUT_DIR): mkdir -p $(OUT_DIR)

Clean build artifacts

clean: rm -rf $(OUT_DIR)/* rm -rf $(BUILD_DIR)/*

Watch for changes (requires entr)

watch: find $(SRC_DIR) -name "*.md" | entr -c make pdf

Help

help: @echo "Available targets:" @echo " all - Build all PDFs (default)" @echo " pdf - Build PDF files" @echo " docx - Build DOCX files" @echo " html - Build HTML files" @echo " clean - Remove built files" @echo " watch - Watch for changes and rebuild" @echo "" @echo "Source files: $(MD_FILES)"

12. GitHub Actions Workflow

.github/workflows/build-docs.yml

name: Build Documents

on: push: branches: [main] paths: - 'docs/' - 'templates/' - '.github/workflows/build-docs.yml' pull_request: paths: - 'docs/' - 'templates/' workflow_dispatch:

jobs: build: runs-on: ubuntu-latest

steps:
  - name: Checkout repository
    uses: actions/checkout@v4

  - name: Install Pandoc
    run: |
      wget https://github.com/jgm/pandoc/releases/download/3.1.11/pandoc-3.1.11-linux-amd64.tar.gz
      tar xzf pandoc-3.1.11-linux-amd64.tar.gz
      sudo mv pandoc-3.1.11/bin/* /usr/local/bin/

  - name: Install pandoc-crossref
    run: |
      wget https://github.com/lierdakil/pandoc-crossref/releases/download/v0.3.17.0/pandoc-crossref-Linux.tar.xz
      tar xf pandoc-crossref-Linux.tar.xz
      sudo mv pandoc-crossref /usr/local/bin/

  - name: Install LaTeX
    run: |
      sudo apt-get update
      sudo apt-get install -y texlive-xetex texlive-fonts-recommended \
        texlive-latex-extra texlive-fonts-extra

  - name: Build PDF documents
    run: |
      mkdir -p output
      for file in docs/*.md; do
        output="output/$(basename "${file%.md}.pdf")"
        echo "Building: $file -> $output"
        pandoc "$file" -o "$output" \
          --pdf-engine=xelatex \
          --toc \
          --number-sections \
          --filter pandoc-crossref \
          --template=templates/report.tex
      done

  - name: Upload artifacts
    uses: actions/upload-artifact@v4
    with:
      name: documents
      path: output/*.pdf

release: needs: build runs-on: ubuntu-latest if: github.event_name == 'push' && github.ref == 'refs/heads/main'

steps:
  - name: Download artifacts
    uses: actions/download-artifact@v4
    with:
      name: documents
      path: output

  - name: Create release
    uses: softprops/action-gh-release@v1
    if: startsWith(github.ref, 'refs/tags/')
    with:
      files: output/*.pdf

Integration Examples

Integration with Git Hooks

#!/bin/bash

.git/hooks/pre-commit

Rebuild PDFs before commit

set -e

Check if any markdown files changed

changed_md=$(git diff --cached --name-only --diff-filter=ACM | grep '.md$' || true)

if [[ -n "$changed_md" ]]; then echo "Rebuilding PDF documents..."

for file in $changed_md; do
    if [[ -f "$file" ]]; then
        output="${file%.md}.pdf"
        echo "  Converting: $file -> $output"
        pandoc "$file" -o "$output" --pdf-engine=xelatex --toc
        git add "$output"
    fi
done

fi

Integration with VS Code Tasks

{ "version": "2.0.0", "tasks": [ { "label": "Pandoc: Build PDF", "type": "shell", "command": "pandoc", "args": [ "${file}", "-o", "${fileDirname}/${fileBasenameNoExtension}.pdf", "--pdf-engine=xelatex", "--toc", "--number-sections" ], "group": { "kind": "build", "isDefault": true }, "presentation": { "echo": true, "reveal": "always" } }, { "label": "Pandoc: Build DOCX", "type": "shell", "command": "pandoc", "args": [ "${file}", "-o", "${fileDirname}/${fileBasenameNoExtension}.docx", "--toc" ] }, { "label": "Pandoc: Watch and Build", "type": "shell", "command": "find . -name '*.md' | entr -c pandoc ${file} -o ${fileDirname}/${fileBasenameNoExtension}.pdf --pdf-engine=xelatex", "isBackground": true, "problemMatcher": [] } ] }

Best Practices

1. Document Structure

title: "Document Title" author: "Author Name" date: "2026-01-17" abstract: | Brief summary of the document content.

Introduction

Opening paragraph...

Background

Context and background information...

Main Content

Section One

Content...

Subsection

More detailed content...

Section Two

Additional content...

Conclusion

Summary and conclusions...

References

::: {#refs} :::

Appendix A: Additional Data {.appendix}

Supplementary material...

2. Image Management

<!-- Recommended image syntax -->

{width=80%}

<!-- With cross-reference --> {#fig:arch width=100%}

See @fig:arch for the overview.

<!-- Multiple images --> ::: {#fig:comparison layout-ncol=2}

{#fig:before}

{#fig:after}

Comparison of results :::

3. Code Block Best Practices

<!-- Named code blocks with line numbers -->

def process_data(data: list) -> dict:
    """Process input data and return results."""
    results = {}
    for item in data:
        results[item.id] = transform(item)
    return results

<!-- Highlighted lines -->

def calculate(x, y):
    total = x + y  # highlighted
    average = total / 2
    return average  # highlighted

4. Table Formatting

<!-- Simple table -->

<!-- Table with caption and reference -->

: Performance metrics {#tbl:perf}

See @tbl:perf for benchmarks.

<!-- Grid tables (more flexible) --> +---------------+---------------+ | Column 1 | Column 2 | +===============+===============+ | Multi-line | Another cell | | content here | | +---------------+---------------+ | More data | Final cell | +---------------+---------------+

Troubleshooting

Common Issues

PDF Engine Not Found

Check if xelatex is installed

which xelatex

Install on Ubuntu

sudo apt-get install texlive-xetex

Use pdflatex instead

pandoc doc.md -o doc.pdf --pdf-engine=pdflatex

Missing LaTeX Packages

Install specific package (TeX Live)

tlmgr install <package-name>

Install common packages

sudo apt-get install texlive-latex-extra texlive-fonts-extra

Check which package provides a file

tlmgr search --file <filename>

Unicode Characters in PDF

Use XeLaTeX for Unicode support

pandoc doc.md -o doc.pdf
--pdf-engine=xelatex
-V mainfont="DejaVu Sans"

Images Not Found

Use resource path

pandoc doc.md -o doc.pdf
--resource-path=.:images:assets

Or use absolute paths in markdown

Citations Not Processing

Ensure --citeproc is included

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

Check BibTeX file syntax

biber --tool refs.bib

Debug Mode

Verbose output

pandoc doc.md -o doc.pdf --verbose

Show intermediate LaTeX

pandoc doc.md -t latex > debug.tex

Check Pandoc version and features

pandoc --version

List supported formats

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

Version History

v1.0.0 (2026-01-17)

• Initial skill creation

• PDF, DOCX, HTML conversion workflows

• Custom LaTeX templates

• Citation management with BibTeX/CSL

• Cross-references with pandoc-crossref

• Lua filters documentation

• Batch conversion scripts

• Makefile integration

• GitHub Actions workflows

Related Resources

• Pandoc User's Guide

• Pandoc Lua Filters

• Citation Style Language

• pandoc-crossref

• LaTeX Templates

• Zotero Integration

Convert documents between any formats with Pandoc - the universal document converter.