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
- 其他.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
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.
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.
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.
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.
virtual-list
Implement efficient virtual scrolling for rendering large lists with DOM recycling, chunk-based rendering, and performance optimizations
verify-directory-structure
Diagnose and resolve file access issues by first verifying the directory structure.