Wikilinks and Aliases

Syntax

A wikilink is a page name in double brackets:

[[Getting Started]]

Optional pieces can be added:

  • Display text: [[Getting Started|the setup guide]] renders as a link reading “the setup guide”.
  • Heading link: [[Getting Started#5. Render]] links to the ## 5. Render heading within that page. Combine with display text: [[Getting Started#5. Render|the render step]].

Case insensitivity: matching against the registry ignores case, so [[getting STARTED]] resolves the same as [[Getting Started]].

Aliases

As mentiong in Getting Started, you can use a Wikilink to reference the title of a page, which is defined in the frontmatter. For example [[A blog post about the Uranus]], will resolve to any page with this yaml frontmatter:

---
title: A blog post about the Uranus
---

You could also reference this page if you gave it an alias with the also-known-as frontmatter key.

Say you want to refer to it as [[uranus-post]], then you could add:

blog/uranus.qmd:

---
title: A blog post about the Uranus
also-known-as: uranus-post
---

Now, you can link to this page blog/uranus.qmd with either:

  • [[A blog post about the Uranus]]
  • [[uranus-post]]

Note case-insentivity applies to both title and alias keys when building connections.

Conflicts

If pages have the same title, how does quarto-graph resolve them?

quarto-graph takes the first one that’s registered and prints:

WARNING: duplicate link target 'name' (first-page.qmd vs second-page.qmd); keeping first-page.qmd

One way to avoid conflicts is to use Aliases, as described above. Another is by qualifying the target with enough of its own folder path to be unique:

  • [[docs/api]]
  • [[vendor/api]]

Note that because aliases are already a deliberately chosen unique name, aliases don’t get this same treatment.

How connections are resolved

quarto-graph relies on quarto inspect to generate the pages of the rendered website, without actually rendering the website. That means, quarto-graph is subject to the Quarto’s behaviour on render targets.

This means:

  • Any qmd/md page that is not README.(q)md, CLAUDE.md, or AGENTS.md. This is to be consistent with Quarto’s render targets behaviour
  • Targets that are ignored / excluded under _quarto.yml are also excluded from the graph (I guess that’s expected behaviour? maybe this is a dev note).

If a page links to a page that doesn’t exist, a warning will be emitted at render1:

WARNING: unresolved wikilink [[THIS IS AN EXAMPLE]] in link/to/offending/page.md

Excludes

To exclude additional pages in the graph widget and backlinks, one can use the exclude key in _quarto.yml:

quarto-graph:
  exclude:
    - archive/       # this directory and everything under it
    - "*.draft.qmd"  # glob pattern, matched against each page's project-relative path

Index.qmd

Quarto by default encourages use of index.qmd to act as landing pages / MOCs.

These pages are treated by taking the stem

Backlinks

Footnotes

  1. To make broken links fail the build instead of just warning, pass --strict to the pre-render script; see CLI. ↩︎