Fix PDF render errors

BNR info-hub Technical Manual

1 Fix PDF render errors

1.1 Purpose

Use this guide when a Quarto Typst PDF briefing fails to render or renders but does not look right.

For the case-count pilot:

site/surveillance/cvd/briefings/case-counts-pdf.qmd

Standard render command:

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

2 Stage 1: Check the PDF QMD location

The PDF QMD should sit beside the HTML briefing QMD:

site/surveillance/cvd/briefings/case-counts.qmd
site/surveillance/cvd/briefings/case-counts-pdf.qmd

3 Stage 2: Check the YAML header

A simple Typst PDF header looks like this:

---
title: "Hospital Cardiovascular Cases in Barbados"
subtitle: "BNR CVD case-count briefing, 2023"
author: "Barbados National Registry"
date: "2026-04-28"
bibliography: []
citeproc: false
csl: apa
format:
  typst:
    output-file: bnr_cvd_cases_2023_v1.pdf
    toc: false
    number-sections: false
    papersize: a4
    margin:
      top: 1.8cm
      bottom: 1.7cm
      left: 1.8cm
      right: 1.8cm
    mainfont: "Open Sans"
    fontsize: 10pt
    linkcolor: "#e87a00"
    fig-cap-location: bottom
---

Do not use:

csl: null

Quarto expects csl to be a string.

4 Stage 3: Check inherited bibliography errors

If the PDF fails with:

unknown style: https://www.zotero.org/styles/harvard-cite-them-right

add:

bibliography: []
citeproc: false
csl: apa

5 Stage 4: Check image paths

If the PDF QMD sits here:

site/surveillance/cvd/briefings/case-counts-pdf.qmd

then image paths to the site download folder usually start with:

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

Example:

![Cumulative CVD cases](../../../downloads/files/briefings/cvd_cases_2023_v1/figures/cases_2023_cum_week.png){width=100%}

6 Stage 5: Understand where the PDF is created

When rendering inside a Quarto website project, the PDF is generated under _site/:

site/_site/surveillance/cvd/briefings/bnr_cvd_cases_2023_v1.pdf

This is expected. Do not edit _site/ directly.

7 Stage 6: Check the visual result

After a successful render, open the PDF and check:

  • title block
  • logo placement if used
  • figure size and clarity
  • page breaks
  • font readability
  • absence of private paths
  • citation/build note if included
Back to top