Skip to main content

Paths in websites

A website is usually developed from a local server rooted at the output directory, but deployed somewhere else — often under a subdirectory of a larger site (https://example.com/docs/). Quarto rewrites the paths you write so the rendered site works in both places. This page explains what you can write, what Quarto does with it, and the one case Quarto deliberately leaves alone.

Two ways to write a path

Everywhere Quarto reads a path — markdown links and images, navbar and footer configuration, logo:, and so on — you can write it in one of two forms:

  • Relative (images/plot.png, ../index.qmd): resolved relative to the file you wrote it in. In configuration files (_quarto.yml, a directory _metadata.yml), relative paths are resolved against the directory of the file that declares them.
  • Site-root-relative (/images/plot.png, /index.qmd): a leading / always means “from the project root”. It never means your filesystem’s root, and it does not mean “from the deployed domain’s root” — Quarto rewrites it before it reaches the browser.

Both forms produce the same rendered output: a page-relative URL. A page two directories deep referencing /images/plot.png emits ../../images/plot.png, so the link keeps working no matter which URL prefix the site is served under.

Links to project documents get the same treatment plus an extension rewrite: [Home](/index.qmd) renders as ../../index.html from that same page.

Configuration-declared assets

Values in _quarto.yml are shared by pages at every depth, so no single literal path could be correct on all of them — this is exactly what the per-page rewrite is for. It applies to:

  • website.navbar.logo
  • logo: on a reveal.js deck (relative to the file that declares it, or site-root-relative with a leading /; the file is copied into the output directory)
  • a listing item’s image: (front matter or inline record), which a leading / anchors at the project root
  • markdown images and links inside page-footer regions and the navbar title
  • navbar, sidebar, and footer item hrefs

Prefer plain markdown for footer imagery:

_quarto.yml
website:
  page-footer:
    left: '[![Logo](/images/logo.svg)](https://example.com)'

The image renders page-relative on every page, and Quarto copies images/logo.svg into the output directory for you. If the file is missing, the render completes with a warning naming the missing path.

Linked files are copied

A markdown link to a local file that is not a page, such as a dataset or a dashboard offered as a download, is copied into the output directory next to the page, the same way an image is:

guide/index.qmd
- [Dashboard](dashboard.json){download="my-dashboard.json"}
- [Data](data.csv)
- [Data, from the root](/guide/data.csv)

guide/dashboard.json and guide/data.csv land in _site/guide/. Quarto finds the file by dropping any ?query or #fragment from the link and decoding %20-style escapes. Links produced by shortcodes and by filters that run before Quarto’s own processing are found too.

A file name that contains spaces can be written with %20, or wrapped in angle brackets, which Quarto encodes for you:

- [Data](my%20data.csv)
- [Data](<my data.csv>)
![A chart](<figures/sales chart.png>)

A link is left alone, and nothing is copied, when its target:

  • is not a file in the project: a URL, a #section anchor, a directory (data/), a file that does not exist, or a path that climbs out of the project;
  • is a project document (.qmd files are never copied this way, even unrendered drafts), or looks like another format’s output of one, such as report.pdf next to report.qmd;
  • is hidden (any part of the path starts with .), or lives in _freeze/ or the output directory.

Only markdown links are examined. A path in raw HTML, in an attribute value (data-href="…"), in code, or in a navbar, sidebar or footer href: is not copied; declare those files under resources (see Raw HTML is not rewritten). An unrendered notebook or .md file that a page links to is copied, which is the usual way to offer a notebook as a download.

Turning it off

Set resource-discovery: false to stop copying linked files. It is ordinary metadata, so it applies at whatever level you set it: a page’s front matter, a directory’s _metadata.yml, the top level of _quarto.yml, or a single format (format: html: resource-discovery: false). An inner level overrides an outer one, so a page can turn discovery back on with resource-discovery: true. On the command line, use -M resource-discovery:false.

The value must be true or false. Anything else, such as a typo like flase, is an error (Q-5-52) and the page is not rendered.

To exclude individual files rather than all of them, remove them from meta.resources in a post filter; see Publishing extra files.

Raw HTML is not rewritten

Quarto 2 does not parse or rewrite HTML you author yourself. A raw HTML block or inline like

`<img src="/images/logo.svg">`{=html}

is emitted byte-for-byte. The /images/... path inside it works from a local server rooted at the output directory and breaks when the site is deployed under a subdirectory — silently, because Quarto does not look inside raw HTML.

If you need an image or link in configuration or content, write it in markdown and let Quarto resolve it. Markdown images support attributes (![alt](/images/x.svg){.my-class width=32}), which covers most reasons to reach for raw HTML.

Files referenced only from raw HTML are also invisible to resource collection, so they are not copied to the output directory. Declare them explicitly to have them copied:

_quarto.yml
project:
  type: website
  resources:
    - images/

Fully-qualified URLs

A URL with a scheme (https://…) or a protocol-relative URL (//host/…) passes through untouched, everywhere. Building asset URLs from site-url works, but hard-codes the deploy location into every page — for versioned documentation that includes the version segment — so prefer site-root-relative paths unless you specifically want an absolute URL.