Linking to pages

This page describes the different ways that quartodoc can link to other pages, where each style of link is used, and how to set them up.

Here are the key details covered on this page:

Link to a page (.qmd file) using the path to the file.
Link to a function name by using the interlinks filter’s special syntaxes.
Link type annotations in documented functions by enabling the interlinks filter.

Guide pages on each linking style

Here are some examples of different linking styles and their corresponding guide pages.

Link syntax	Example	Guide page
Qmd path	`[get_object](/reference/get_object.qmd)`	Quarto - markdown basics
Interlink (full)	[](`quartodoc.get_object`)	Interlinks filter
Interlink (autolink)	`quartodoc.get_object`	Interlinks filter - autolink mode

Linking by path

You can use quarto’s markdown linking syntax to link to function docs, by using the path to the generated documentation file.

Here are some examples:

code	result
`[get_object](/reference/get_object.qmd)`	get_object
`[link text](/reference/MdRenderer.qmd)`	link text

Shortening anchors

When several objects are documented on one page, each gets an anchor (the part of a URL after the #). By default that anchor is the object’s full path, so a method lands at a URL like /reference/MdRenderer.html#quartodoc.MdRenderer.render.

Set the short_anchors option to strip the module path, which shortens that to /reference/MdRenderer.html#MdRenderer.render:

quartodoc:
  package: quartodoc
  options:
    short_anchors: true

Only the anchor changes. File names are unaffected, and inventory entries are still keyed on the full path, so interlinks like [](`quartodoc.MdRenderer.render`) keep working and resolve to the new anchor.

Two things to keep in mind before turning this on. Anchors only need to be unique within a page, and objects from the same module cannot collide once the shared module path is stripped — but a hand-written Page that gathers objects from different modules can, if two of them have the same class-relative name. And if you are migrating from Sphinx, note that the default full-path anchors are identical to the ones Sphinx generates, so shortening them means old links with an anchor will land on the page but not on the heading.

Linking by function name

Use quartodoc’s interlinking filter to link to functions using only their names:

code	result
[](`quartodoc.get_object`)	`quartodoc.get_object`

Notice that the link above puts the function name in backticks, rather than using the path to its documentation: `quartodoc.get_object`.

You can also use this approach to link to other documentation sites. For example, including links to quartodoc, or https://docs.python.org/3 using function names.

See the interlinks documentation for set up and usage.

The “See Also” section

A major goal of quartodoc is to automatically turn text in the “See Also” section of docstrings into links.

See this issue for more details on parsing See Also sections, and this issue on turning type annotations into links.

Type annotations in docstrings

Creating links from type annotations for a function and their reference pages is supported via the interlinks filter. See the Rendering Interlinks in API Docs section on the interlinks page for more.

Essentially, interlinking type annotations requires:

Setting the quartodoc render_interlinks config option to true.
Enabling the interlinks filter.