AGENT SKILL

pandoc-pdf-error-recovery

Systematic approach to diagnose and recover from pandoc PDF conversion unknown errors

使用场景文档处理
License 许可
MIT
所属仓库
AG064/OpenSpace
最近更新
2026-10-08
Stars
★ 0
Forks
0

01 前言 Front Matter

name
pandoc-pdf-error-recovery
description
Systematic approach to diagnose and recover from pandoc PDF conversion unknown errors

02 资源文件 1

03 SKILL.md 正文

Pandoc PDF Error Recovery

Overview

When pandoc fails to convert documents to PDF with an "unknown error" or similar vague message, follow this systematic diagnostic and recovery workflow.

Step-by-Step Procedure

1. Verify Pandoc Installation

First confirm pandoc is installed and accessible:

pandoc --version

If this fails, install pandoc before proceeding:

2. Check Available PDF Engines

Identify which PDF rendering engines are available on the system:

which pdflatex xelatex lualatex wkhtmltopdf context

Common engines and their typical use cases:

  • pdflatex: Standard LaTeX, fast but limited Unicode support
  • xelatex: Full Unicode support, recommended for most modern documents
  • lualatex: Lua scripting support, good for complex layouts
  • wkhtmltopdf: HTML/CSS rendering, good for web-style documents
  • context: ConTeXt typesetting system

3. Attempt Conversion with Explicit Engine

Try conversion with xelatex first (most versatile for general documents):

pandoc input.md -o output.pdf --pdf-engine=xelatex 2>&1 | tee conversion.log

The 2>&1 | tee pattern captures both stdout and stderr to a log file for analysis.

4. Analyze Error Output

If conversion fails, examine the captured log:

cat conversion.log

Common error patterns and solutions:

  • Missing LaTeX packages: Install with tlmgr install <package> or system package manager
  • Font issues: Specify fonts with -V mainfont="Font Name"
  • Missing engine: Fall back to available engine (go to Step 5)

5. Try Alternative Engines

Systematically try other available engines:

# Fallback to pdflatex
pandoc input.md -o output.pdf --pdf-engine=pdflatex 2>&1 | tee conversion-pdflatex.log

# Or try wkhtmltopdf for HTML-rich content
pandoc input.md -o output.pdf --pdf-engine=wkhtmltopdf 2>&1 | tee conversion-wkhtmltopdf.log

# Or try lualatex for complex documents
pandoc input.md -o output.pdf --pdf-engine=lualatex 2>&1 | tee conversion-lualatex.log

6. Install Missing Dependencies

If all engines fail or are missing, install required packages:

# Full TeX Live installation (comprehensive but large)
sudo apt-get install texlive-full

# Or minimal installation with common packages
sudo apt-get install texlive-latex-base texlive-fonts-recommended

# For xelatex font support
sudo apt-get install fonts-noto fonts-dejavu

7. Simplify and Retry

If errors persist, try conversion with minimal options:

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

Remove complex formatting, custom headers, or advanced LaTeX features that may be causing issues.

Quick Reference Command

Complete diagnostic one-liner:

pandoc --version && which pdflatex xelatex wkhtmltopdf && pandoc input.md -o output.pdf --pdf-engine=xelatex -v

Tips

  • Always capture stderr (2>&1) to see the actual error message
  • Use -v (verbose) flag for more detailed output during troubleshooting
  • For non-English documents, xelatex or lualatex are usually required
  • HTML/CSS-heavy documents may work better with wkhtmltopdf
  • Check system disk space - PDF generation can require significant temporary space

04 同仓库更多 Skills