Portable Links

Quarto Extension

Author

Mickaël CANOUIL, Ph.D.

See the extension overview for installation and usage.

What it does

In a Quarto website or book, relative links to other pages resolve only within the HTML site. When the document is rendered to a non-HTML format (PDF, DOCX, Typst), those pages do not exist alongside the output and the links break. This filter rewrites them to absolute URLs built from the project’s site-url.

This page renders to HTML, where relative cross-page links already work, so the filter leaves them untouched.

Cross-page links

These relative links are rewritten in non-HTML formats:

  • A page link: [methods page](methods.qmd).
  • An anchored link: [appendix notes](appendix.html#notes).
  • A query-string link: [search results](search.html?q=portable).
  • A nested relative path: [chapter two](chapters/02-intro.qmd).
  • A root-relative path: [chapter three](/chapters/03-summary.qmd).
  • A current-directory path: [chapter four](./chapters/04-discussion.qmd).

These links are never rewritten:

  • An external link: [Quarto](https://quarto.org).
  • A protocol-relative link: [CDN asset](//cdn.example.com/asset.html).
  • An in-page anchor: [jump to top](#what-it-does).
  • An email link: [contact](mailto:hello@example.com).
  • A file whose name only contains .qmd as part of a longer suffix: [backup notes](methods.qmd.backup).

Before and after

With this project’s site-url, a non-HTML render produces:

Source Rewritten target
methods.qmd https://m.canouil.dev/quarto-portable-links/methods.html
appendix.html#notes https://m.canouil.dev/quarto-portable-links/appendix.html#notes
search.html?q=portable https://m.canouil.dev/quarto-portable-links/search.html?q=portable
chapters/02-intro.qmd https://m.canouil.dev/quarto-portable-links/chapters/02-intro.html
/chapters/03-summary.qmd https://m.canouil.dev/quarto-portable-links/chapters/03-summary.html
./chapters/04-discussion.qmd https://m.canouil.dev/quarto-portable-links/chapters/04-discussion.html