Troubleshooting

Troubleshooting

Start with diagnostics

pnpx @skxv/leafmark doctor

Then rebuild with intermediate files retained:

pnpx @skxv/leafmark --keep-build-files

pandoc not found

Install Pandoc and restart the terminal so PATH is refreshed. See Installation.

No LaTeX engine found

Install XeLaTeX or pdfLaTeX. XeLaTeX is recommended for system and OpenType fonts. If only HTML is needed, use --html-only.

LaTeX package or font errors

• Inspect Pandoc/LaTeX's reported missing package or font.
• Verify font names and local font paths.
• Inspect dist/_pandoc-fonts.tex and _pandoc-build-includes.tex with --keep-build-files.
• Ensure theme LaTeX includes are compatible with the chosen engine.

coverpage requires pdfunite

Install Poppler, use --no-merge-cover, or remove coverpage. Confirm the configured cover exists and is already a PDF.

Expected YAML front matter

The configured frontmatter file must begin with a fenced YAML document:

---
title: Example
---

If the file is normal chapter content, rename it or set frontmatter: false in config.

Missing CSS style

styles must be a YAML list and each file must exist relative to the active project:

styles:
  - styles/report.css

Do not write styles: styles/report.css as a scalar.

HTML image syntax appears as text

Update Leafmark to the latest version. For fenced HTML, ensure the opening language is html or htm and that the closing fence uses the same character with at least the same length:

```html
<div class="card">Rendered content</div>
```

The generated image Markdown must not remain inside an unterminated code fence.

Cannot find _html-blocks images

They are temporary and are deleted after a successful build. The images have already been embedded into the PDF or DOCX. Use:

pnpx @skxv/leafmark --keep-build-files

HTML blocks require a browser

Install Chrome, Chromium, Edge, or Brave in its normal platform location. This is required only for HTML blocks in PDF/DOCX; --html-only preserves HTML without screenshotting it.

HTML block is blank or styled incorrectly

• Confirm every stylesheet path exists.
• Use a visible background and text color.
• Ensure local fonts and image resources resolve.
• Remember that JavaScript is disabled.
• Inspect the generated PNG with --keep-build-files.
• Split very tall blocks.

Citations are unresolved

• Confirm the bibliography file exists.
• Check that [@key] exactly matches a BibTeX entry key.
• Ensure bibliography is not false or empty.
• Fix malformed BibTeX before rebuilding.

Wrong chapter order

Run leafmark order, inspect the config order array, or pass chapter names explicitly. Files not present in the saved order are appended.

Wrong project or output directory

Run leafmark status <folder> to confirm the active input and chapters. A direct .md target writes beside the source by default; folder builds write to ./dist. Use --output for an explicit location.

Theme changes disappeared

theme use replaces .leafmark/theme/. Store reusable changes in a theme repository, or keep project-specific overrides outside that directory.

header-includes is rejected

Leafmark owns the generated PDF preamble. Move custom LaTeX into a theme include, fonts.latexInclude, or a Lua/Pandoc extension.

Watch mode rebuilds repeatedly

Ensure output is not placed inside a watched non-ignored source path. The normal workspace output root is ignored automatically; unusual custom paths can create noisy workflows.

Still stuck

Collect:

1. leafmark doctor output;
2. the exact command;
3. the full error;
4. relevant config/frontmatter with secrets removed;
5. Leafmark, Node, and Pandoc versions;
6. a minimal reproducing chapter.

Then open an issue in the Leafmark repository.