Troubleshooting

PDF export fails

99% of the time: missing Pandoc / LaTeX or PATH issue; the remaining 1% is a special character in the doc.

Symptom

You click File → Export → PDF and get a red error: "Export failed: pandoc not found" or "pdflatex returned non-zero exit code". Sometimes the PDF is created but it is 0 KB, or all Chinese characters are missing.

Kition’s PDF export goes through Pandoc + LaTeX — the most stable open-source typesetting stack, but it has to be installed once on your system. After PATH is wired up it rarely breaks again.

Likely causes

Pandoc not installed (symptom: "pandoc not found")
LaTeX engine missing (symptom: "pdflatex / xelatex not found")
PATH does not include Pandoc / LaTeX bin (installed but Kition cannot see it)
Doc has CJK characters but is using default pdflatex (no Unicode support)
Image paths contain spaces or non-ASCII; pandoc cannot resolve them
No write permission on the export target dir (e.g., you picked / on macOS)

One-time install

macOS — Homebrew is the easiest path:

# macOS: pandoc + a minimal TeX distribution
brew install pandoc
brew install --cask basictex

# After basictex installs, refresh PATH in current shell:
eval "$(/usr/libexec/path_helper)"

# Verify
pandoc --version
which xelatex

# If you write Chinese / Japanese / Korean, also install CJK fonts:
sudo tlmgr update --self
sudo tlmgr install collection-langchinese collection-fontsrecommended

Windows install

Download the Windows MSI from pandoc.org/installing.html
Install MiKTeX from miktex.org/download (basic installer — installs packages on demand)
Restart Kition after install (otherwise it reuses the old PATH)
In PowerShell, run pandoc --version to confirm it resolves

Step-by-step diagnostic

Run which pandoc / where.exe pandoc in a terminal to confirm it is found
Run which xelatex to confirm the LaTeX engine is on PATH
Try a minimal CLI conversion: pandoc test.md -o test.pdf --pdf-engine=xelatex
In Settings → Export → Engine, switch from pdflatex to xelatex (Unicode support)
Check Kition logs: grep -i "pandoc\|xelatex" ~/Library/Logs/Kition/main.log | tail -20
After a failed export, look in Kition’s temp dir for a .log file — LaTeX’s real error lives there

Fix

Restart Kition after install — PATH only refreshes on new processes
Missing CJK glyphs: switch the engine to xelatex and pick an installed CJK font in Settings → Export → "Main font"
Image not found: keep images inside the vault, use relative paths, avoid spaces and non-ASCII in paths
PATH blind: Settings → Export → "Custom binary path" — point at /Library/TeX/texbin/xelatex
Permission denied: pick a different export folder, e.g., ~/Downloads/

Workaround

If you only need one PDF and do not want to install the whole LaTeX stack today: File → Export → HTML, open in a browser, Print → "Save as PDF". Visually ~90% there, fine for most sharing.

For batch exports, run it from the shell: for f in *.md; do pandoc "$f" -o "${f%.md}.pdf" --pdf-engine=xelatex; done.

When to file a bug

CLI pandoc converts the exact same doc fine, Kition fails
No log line shows pandoc being invoked (the UI never actually triggered the export)
xelatex takes > 60s on a medium doc (under 10 pages)
PDF generates but every emoji is a tofu block (should auto-fallback fonts)

← Back to help center More in Troubleshooting →

Exporting to PDF / DOCX

Built-in Pandoc pipeline — export to PDF / DOCX / HTML in one click.