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.logologo: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-footerregions and the navbar title - navbar, sidebar, and footer item
hrefs
Prefer plain markdown for footer imagery:
_quarto.yml
website:
page-footer:
left: '[](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 link is left alone, and nothing is copied, when its target:
- is not a file in the project: a URL, a
#sectionanchor, a directory (data/), a file that does not exist, or a path that climbs out of the project; - is a project document (
.qmdfiles are never copied this way, even unrendered drafts), or looks like another format’s output of one, such asreport.pdfnext toreport.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 ({.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.