Portable Links

Relative links that still work once the site is left behind.

What the portable-links extension is for, how to enable it, and what a relative cross-page link becomes in a PDF.

Author

In a Quarto website or book, [the methods](methods.qmd) resolves because the reader is on the site and the other page is next to it. Render the same document to PDF, Word, Typst, or a slide deck, and the file travels on its own: the target is not there, and the link is dead.

portable-links rewrites those links for the formats that leave the site behind. A relative cross-page link becomes an absolute one built from the project’s site-url, so it points at the published page instead of a file that is not there.

Installation

quarto add mcanouil/quarto-portable-links@0.3.1

This will install the extension under the _extensions subdirectory. If you are using version control, you will want to check in this directory.

Or install it from your editor with Quarto Wizard:

Visual Studio Code Positron VSCodium

Quick start

The filter needs the project’s site-url, which belongs in the project configuration rather than a document:

website:
  site-url: "https://example.com/my-site"

Enable the filter:

filters:
  - portable-links

Then write links exactly as you would for the website:

See the [methods page](methods.qmd) and [the appendix](appendix.html#notes).

In HTML nothing changes. In a PDF, a Word file, or a deck, those become https://example.com/my-site/methods.html and https://example.com/my-site/appendix.html#notes.

Seeing it work

This site is HTML, so the filter deliberately leaves its pages alone. The Typst preview is the same site rendered to a format that does leave it behind, and its links point back here.

See the Reference for the rewriting rules, and the Examples for each of them.

Where it works

Which formats the filter touches.
Rewritten	Left alone
PDF, LaTeX, Typst, Word, PowerPoint, and every other non-HTML format.	Plain HTML, format extensions built on `html`, and `epub`.
The HTML slide formats: `revealjs`, `slidy`, `s5`, `dzslides`, `slideous`.

A slide deck is self-contained even though it is HTML, so cross-page links do not resolve in it and it is rewritten too.