pandoc-pdf-error-diagnosis
Systematic diagnostic workflow for resolving pandoc PDF conversion errors
- License 许可
- MIT
- 所属仓库
- AG064/OpenSpace
- 最近更新
- 2026-10-08
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- pandoc-pdf-error-diagnosis
- description
- Systematic diagnostic workflow for resolving pandoc PDF conversion errors
02 资源文件 1
- 其他.skill_id40 B
03 SKILL.md 正文
Pandoc PDF Error Diagnosis Workflow
When pandoc reports an "unknown error" during PDF conversion, follow this systematic diagnostic workflow to identify and resolve the issue.
Step 1: Verify Pandoc Installation
First, confirm pandoc is installed and check its version:
pandoc --version
This verifies pandoc is available and shows which version and features are supported.
Step 2: Check Available PDF Engines
Identify which PDF rendering engines are installed on the system:
which pdflatex xelatex lualatex wkhtmltopdf
Common engines and their characteristics:
- pdflatex: Fast, widely available, good for simple documents
- xelatex: Better Unicode/font support, handles modern fonts well
- lualatex: Advanced Lua scripting, modern TeX features
- wkhtmltopdf: HTML-to-PDF via WebKit, good for web-styled content
Step 3: Attempt Conversion with Explicit Engine
Try conversion with an explicit engine specification, starting with xelatex (most forgiving):
pandoc input.md -o output.pdf --pdf-engine=xelatex
Important: Capture the full stderr output for diagnosis:
pandoc input.md -o output.pdf --pdf-engine=xelatex 2>&1 | tee conversion.log
Step 4: Analyze Error Output
Examine the captured stderr for common issues:
| Error Pattern | Likely Cause | Solution |
|---|---|---|
xelatex not found |
Engine not installed | Install TeX Live or try different engine |
Package xyz not found |
Missing LaTeX package | Install missing package or remove feature |
Font xyz not found |
Missing font | Install font or change document fonts |
LaTeX Error: File xyz.sty not found |
Missing style file | Install texlive-extra or simplify document |
Step 5: Fallback Strategy
If the primary engine fails, try alternatives in order:
# Try pdflatex (most basic)
pandoc input.md -o output.pdf --pdf-engine=pdflatex 2>&1
# Try lualatex (if xelatex failed)
pandoc input.md -o output.pdf --pdf-engine=lualatex 2>&1
# Try wkhtmltopdf (for HTML-heavy content)
pandoc input.md -o output.pdf --pdf-engine=wkhtmltopdf 2>&1
Step 6: Install Missing Dependencies (if possible)
If a specific engine is needed but missing:
# Debian/Ubuntu
sudo apt-get install texlive-xetex texlive-fonts-recommended
# macOS with Homebrew
brew install --cask mactex-no-gui
# Check what's available
tlmgr install <package-name>
Step 7: Simplify and Retry
If all engines fail, simplify the source document:
- Remove complex tables or math
- Replace custom fonts with standard fonts
- Split large documents into sections
- Convert to intermediate format first (e.g., HTML then PDF)
Quick Reference Diagnostic Script
#!/bin/bash
# pandoc-pdf-diagnose.sh
INPUT="${1:-input.md}"
OUTPUT="${2:-output.pdf}"
echo "=== Pandoc PDF Conversion Diagnosis ==="
echo "Input: $INPUT"
echo "Output: $OUTPUT"
echo ""
echo "1. Pandoc version:"
pandoc --version | head -1
echo ""
echo "2. Available engines:"
for engine in pdflatex xelatex lualatex wkhtmltopdf; do
if which $engine > /dev/null 2>&1; then
echo " ✓ $engine: $(which $engine)"
else
echo " ✗ $engine: not found"
fi
done
echo ""
echo "3. Attempting conversion with xelatex:"
pandoc "$INPUT" -o "$OUTPUT" --pdf-engine=xelatex 2>&1
if [ $? -eq 0 ]; then
echo "✓ Conversion successful!"
else
echo "✗ Conversion failed. Try alternative engines."
fi
When to Use This Skill
- Pandoc reports "unknown error" during PDF conversion
- PDF output is empty or corrupted
- Need to determine which PDF engine works best for a document
- Troubleshooting CI/CD pipeline document generation failures
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.