Quarto does not copy images referenced from raw HTML

Images pulled in by an or SVG are invisible to Quarto’s resource discovery, so they go missing from _site. Declare them with resources.

Quarto works out which files to copy into _site/ by scanning the rendered document for things that look like assets. That scan understands Markdown image syntax and the HTML that Quarto itself generates from it, so the usual case just works:

![Custom controller internals](K8s-custom-controller.png)

It does not understand assets you reference from raw HTML you wrote by hand. An inline SVG that pulls in bitmaps through <image href> is the case that bit me:

<svg viewBox="0 0 1120 420">
  <image href="cc-router.png" x="0" y="0" width="260" height="180" />
</svg>

That renders correctly in quarto preview, because the preview server is serving files straight out of the project directory. It breaks on quarto render, where the images were never copied across and every figure resolves to a 404.

The fix is to declare the files explicitly in the page’s front matter:

---
title: "..."
resources:
  - "*.png"
---

resources accepts globs and takes paths relative to the document, so "*.png" covers a directory of figures without listing each one.

Tip

Preview will not catch this, so it is worth running a real quarto render and opening the page out of _site/ before publishing anything that uses hand-written HTML for its figures.

You can also set resources at the project level in _quarto.yml, but keep it on the page when only that page needs it. A project-wide glob copies the matching files from every directory, including ones you meant to leave out.