Skip to content
A fast, modern Sphinx theme with dark mode, full-text search, and Alpine.js interactivity. Star on GitHub ★
Sphinx Lumina Theme

Footnotes & References

Cross-referencing, citations, glossaries, and linking across documents and projects.

Footnotes

Auto-numbered footnotes add citations to the bottom of the page.

Sphinx was created by Georg Brandl[1] and is the de facto standard for Python documentation[2].

The MyST syntax:

Some text with a footnote[^1].

[^1]: Footnote content here.

Cross-References

Document References

Link to other pages in the documentation using the {doc} role.

See the Typography page for text formatting options, or check out Code Blocks for syntax highlighting.

The MyST syntax:

{doc}`page-name`
{doc}`custom link text <page-name>`

Section References

Create a label above any heading and reference it with {ref}.

This section can be referenced from anywhere as Section References.

The MyST syntax:

(my-label)=
### My Section

Link to it with {ref}`my-label` or {ref}`custom text <my-label>`.

Glossary

Define terms in a glossary and reference them with the {term} role.

MyST

Markedly Structured Text — a Markdown flavor designed for Sphinx that supports directives and roles.

Sphinx

A documentation generator that converts reStructuredText and MyST Markdown into HTML, PDF, and other formats.

directive

A block-level extension in Sphinx that adds special content like admonitions, code blocks, and tables of contents.

role

An inline extension in Sphinx that adds semantic meaning to text, such as cross-references, math, and abbreviations.

The MyST parser allows you to write Sphinx documentation in Markdown. Use directives for block content and roles for inline content.

The MyST syntax:

```{glossary}
Term
  Definition of the term.
```

Reference it with {term}`Term`.

Substitutions

Define reusable text snippets in conf.py and use them across pages.

This documentation is for Sphinx Lumina Theme version 1.35.0.

The MyST syntax:

This is for {{project_name}} version {{version}}.

Substitutions are defined in conf.py:

myst_substitutions = {
    "project_name": "Sphinx Lumina Theme",
    "version": "0.1.0",
}

Version Directives

Document when features were added, changed, or deprecated.

Added in version 1.2.0: The nav_links option now supports dropdown menus via the children key.

Changed in version 1.5.0: The search_backend option now defaults to "pagefind" instead of "sphinx".

Deprecated since version 1.8.0: The legacy_search option. Use search_backend instead.

The MyST syntax:

```{versionadded} 0.1.0
Description of what was added.
```

```{versionchanged} 0.2.0
Description of what changed.
```

```{deprecated} 0.3.0
Description of what was deprecated.
```

Intersphinx

Link to objects in other Sphinx documentation projects — Python standard library, third-party packages, or your own related projects.

Setup

conf.py
extensions = ["sphinx.ext.intersphinx"]

intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
}

Usage

Reference any documented object from the mapped project:

See {py:class}`python:pathlib.Path` for path manipulation.

Read about {doc}`sphinx:usage/configuration` for conf.py options.

The {py:func}`python:json.dumps` function serializes Python objects to JSON.

Tip

Use python: as a prefix to avoid conflicts when your own project defines objects with the same name as Python built-ins.

Finding Available References

List all objects available from an intersphinx mapping:

python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv

This outputs every referenceable object, which you can search for the exact role and name to use.