Cross-Referencing

Great Docs provides a linking system called GDLS (Great Docs Linking System) that automatically creates clickable navigation between your API reference pages. GDLS operates at three levels, each adding a different kind of connectivity to your documentation.

The first level is the %seealso directive, which adds structured “See Also” sections that link related items together. The second level is inline interlinks, which let you create Markdown-style links to API symbols anywhere in your prose. The third level is code autolinks, which automatically turn inline code references like `MyClass` into clickable links when they match a documented symbol.

All three mechanisms resolve against the same objects.json inventory that Great Docs generates during the build. To preview which symbols are available for linking before you build, run:

great-docs scan

The `%seealso` Directive

The %seealso directive adds a “See Also” section to a reference page. Place it anywhere in a docstring with a comma-separated list of related names:

def encode(data: bytes, encoding: str = "utf-8") -> str:
    """Encode bytes to a string.

    %seealso decode, transcode
    """
    ...

Great Docs strips the directive from the rendered output and generates a “See Also” section with clickable links at the bottom of the page.

Names can reference any exported symbol, including class methods using dotted notation:

class Validator:
    def check(self, data):
        """Run all validation checks.

        %seealso Validator.reset, Report
        """
        ...

Adding Descriptions

You can add a short description after each name, separated by a colon. When descriptions are present, the See Also section renders as a list with each link followed by its description. Without descriptions, the links appear as a compact comma-separated line.

def load(path: str) -> dict:
    """Load data from a file.

    %seealso save : Write data back to a file, validate : Check data integrity
    """
    ...

You can mix entries with and without descriptions freely:

def transform(data: dict) -> dict:
    """Transform data before processing.

    %seealso validate : Check data integrity first, load, save
    """
    ...

NumPy-style See Also Sections

If your docstrings use the NumPy docstring format, you can write a standard See Also section instead of (or in addition to) the %seealso directive. Great Docs recognizes this format, preserves the descriptions, and merges it with any %seealso entries on the same page. Duplicate references are deduplicated automatically.

def connect(host: str, port: int = 5432):
    """Open a connection to the server.

    Parameters
    ----------
    host
        The server hostname.
    port
        The port number.

    See Also
    --------
    disconnect : Close an open connection.
    send : Transmit data over the connection.
    """
    ...

Inline Interlinks

You can create inline links to other API items anywhere in your docstring text using the interlinks syntax. This is especially useful in class hierarchies and overview docstrings where you want to point readers to related pages. There are several forms:

Write [](`~mypackage.MyClass`) to display just MyClass. The ~ prefix strips the package path and shows only the short name.
Write [](`mypackage.MyClass`) to display the full path mypackage.MyClass.
Write [see this class](`mypackage.MyClass`) to display see this class as the link text.
Write [see this class](`~mypackage.MyClass`) to also display see this class. When you supply custom link text in the brackets, it is always used as-is regardless of the ~ prefix.

Here is an example showing interlinks in practice:

class BaseStore:
    """Base class for all stores.

    Available implementations:

    - [](`~mypackage.DuckDBStore`): local storage with embedded search.
    - [](`~mypackage.ChromaDBStore`): vector storage using ChromaDB.

    See [](`mypackage.BaseStore`) for the full API, or
    [the DuckDB guide](`~mypackage.DuckDBStore`) for a walkthrough.
    """
    ...

In the rendered documentation, each interlinks reference becomes a clickable link pointing to the target’s reference page. Interlinks work in any part of a docstring: the summary line, extended description, parameter descriptions, notes, or any other section.

Code Autolinks

Great Docs automatically converts inline code in docstrings into clickable links when the code matches a documented API symbol. No special syntax is needed; you use standard backtick code formatting and Great Docs does the rest:

class Engine:
    """Core processing engine.

    Use `Pipeline` to chain multiple engines together.
    Call `run_pipeline()` to execute a full pipeline.
    """
    ...

In the rendered output, `Pipeline` and `run_pipeline()` become clickable links to their respective reference pages.

Shortening Prefixes

For qualified names, you can control the display text with ~~ prefixes. The double tilde strips everything before the last component of the dotted path:

What you write	What renders	What it links to
`mypackage.MyClass`	`mypackage.MyClass`	MyClass page
`mypackage.my_func()`	`mypackage.my_func()`	my_func page
`~~mypackage.MyClass`	`MyClass`	MyClass page
`~~mypackage.my_func()`	`my_func()`	my_func page
`~~.mypackage.MyClass`	`.MyClass`	MyClass page

If the name does not match any documented symbol (e.g., `~~unknown_func()`), it renders as plain code with no link.

What Gets Autolinked

Any inline code that looks like an identifier or dotted path is a candidate for autolinking. Parentheses at the end are allowed. Code that contains arguments, spaces, or operators is not linked.

Examples that will be linked (if the name exists in the API):

`MyClass`
`my_func()`
`mypackage.MyClass`

Examples that will not be linked:

`my_func(x=1)` (contains arguments)
`a + b` (contains operators)
`-MyClass` (starts with an operator)

Disabling Autolinks

To prevent a specific piece of inline code from being autolinked, add the {.gd-no-link} class after the backtick span:

The `Config`{.gd-no-link} parameter is a plain dictionary, not the Config class.

This is useful when a word happens to match a documented symbol but you are referring to something else in context.

Best Practices for Linking

Cross-references make documentation much more navigable, but a few guidelines help keep them useful rather than distracting.

Use %seealso to connect items that serve complementary roles. If encode() and decode() are a natural pair, linking them together helps readers discover both. For larger groupings, a brief description after each name (using the colon syntax) gives context about why the link is relevant.

Use inline interlinks when you mention another symbol in the middle of a prose explanation. This keeps reading flow natural while still giving readers a path to the referenced page. The shortened form (with ~) is usually the best choice because fully qualified paths can be long and interrupt the sentence visually.

Code autolinks require no effort on your part, since they happen automatically. But be aware that common words like Config or Data might match a symbol unexpectedly. If you notice unwanted links in the rendered output, add {.gd-no-link} to the specific code span.

Next Steps

API Documentation covers how discovery and organization work
Configuration covers the functional settings in great-docs.yml
Theming & Appearance covers visual customization options

The %seealso Directive