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:

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

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.