AGENT SKILL

pandoc-pdf-error-recovery

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

使用场景文档处理
License 许可
MIT
最近更新
2026-04-16
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

UF-gzj
UF-gzj/openspace-claude-evolution

write-special-chars-ts-check

Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, plus a reliable TypeScript type-checking step that filters output to only the newly-written files to avoid being misled by pre-existing errors.

★ 0
UF-gzj
UF-gzj/openspace-claude-evolution

write-special-chars-readback

Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, with mandatory post-write verification via read_file and cleanup of /tmp helper scripts.

★ 0
UF-gzj
UF-gzj/openspace-claude-evolution

write-special-chars-heredoc

Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) by using a Python heredoc script executed via shell.

★ 0
UF-gzj
UF-gzj/openspace-claude-evolution

worldmonitor-reference

Curated architecture index of the WorldMonitor open-source dashboard. Reference for extracting patterns — vanilla TypeScript, Panel class hierarchy, service layer, CSS grid, API edge functions, refresh scheduler, and 60+ data source integrations.

数据分析师
★ 0
UF-gzj
UF-gzj/openspace-claude-evolution

virtual-list

Implement efficient virtual scrolling for rendering large lists with DOM recycling, chunk-based rendering, and performance optimizations

★ 0
UF-gzj
UF-gzj/openspace-claude-evolution

verify-directory-structure

Diagnose and resolve file access issues by first verifying the directory structure.

★ 0