Fix Quarto render errors

BNR info-hub Technical Manual

1 Fix Quarto render errors

1.1 Purpose

Use this guide when quarto preview or quarto render fails.

Common causes are:

  • invalid YAML
  • a missing file
  • a broken image or download path
  • unsupported syntax in the selected output format
  • inherited project settings that do not work for a specific document

2 Stage 1: Run from the correct folder

cd C:\yoshimi-hot\output\analyse-bnr\info-hub\site

Then run:

quarto preview --port 4200

or:

quarto render

3 Stage 2: Read the first error

Look for messages such as:

YAML front matter failed
File not found
Pandoc failed
Typst compilation failed

The first meaningful error is usually the one to fix.

4 Stage 3: Check YAML

Every QMD file should start with valid YAML between --- lines.

---
title: "Example page"
format:
  html:
    toc: true
---

Common mistakes include invalid indentation, missing quotes, invalid field values, and an unclosed YAML block.

Typst can fail if a QMD inherits a site-wide CSL URL.

For a PDF briefing that does not use citations, use:

bibliography: []
citeproc: false
csl: apa

5 Stage 4: Check missing files

If Quarto cannot find an image or file, check the relative path from the QMD file location.

For a QMD file in:

site/surveillance/cvd/briefings/

a link to the case-count figure folder usually starts with:

../../../downloads/files/briefings/cvd_cases_2023_v1/figures/

6 Stage 5: Render one file if needed

cd C:\yoshimi-hot\output\analyse-bnr\info-hub\site
quarto render surveillance/cvd/briefings/case-counts.qmd

For a PDF briefing:

quarto render surveillance/cvd/briefings/case-counts-pdf.qmd --to typst

7 Stage 6: Restart preview if needed

Stop preview with:

Ctrl + C

Then restart:

quarto preview --port 4200

The _site/ folder is generated by Quarto and ignored by Git.

Fix the QMD source files under site/, not the rendered output under _site/.

Back to top