pandoc-pdf-error-recovery
Systematic approach to diagnose and recover from pandoc PDF conversion unknown errors
- License 许可
- MIT
- 最近更新
- 2026-04-06
- 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
- 其他.skill_id39 B
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:
- macOS:
brew install pandoc - Linux:
sudo apt-get install pandocorsudo yum install pandoc - Windows: Download from https://pandoc.org/installing.html
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
zip-export-deliverable
Ensures codebase deliverables are properly exported as ZIP archives through a dedicated finalization step
zip-deliverable-finalization
Ensure codebase deliverables are properly packaged as ZIP exports in a dedicated final step
zero-iteration-failure-analysis
Identify and handle agent failures with 0 iterations as pre-execution system issues
write-file-fallback-report
Generate professional documents using write_file when primary data sources fail, leveraging embedded domain knowledge instead of external retrieval
fallback-doc-with-delegation
Generate professional documents after tool failures using shell_agent for complex formats or write_file for simple text/markdown
context-anchored-fallback-report
Generate documents with write_file when retrieval tools fail, with explicit guardrails against task context drift