sphinx-substitution-extensions 2026.8.2

code-block

This adds a :substitutions: option to Sphinx’s built-in code-block directive.

.. code-block:: shell
   :substitutions:

   echo "|author| released version |release|"

Inline :substitution-code:

:substitution-code:`echo "|author| released version |release|"`

substitution-download

:substitution-download:`|author|'s manuscript <|author|_manuscript.txt>`

External hyperlinks

Enable substitutions in external hyperlink targets in conf.py:

"""Configuration for Sphinx."""

substitutions_hyperlink_targets_enabled = True

Then substitutions are applied to hyperlink targets:

Download version |release| from the tarball_.

.. _tarball: https://example.com/releases/v|release|.tar.gz

The setting enables hyperlink-target substitutions throughout the project, but only targets containing a defined substitution are changed. To limit a substitution to one page, define it in that page instead of in rst_prolog:

.. |tarball-release| replace:: 0.8.5

Download the tarball_.

.. _tarball: https://example.com/releases/v|tarball-release|.tar.gz

To limit the substitution to one link on that page, use a unique substitution name, such as tarball-release above, only in that link’s target. Other hyperlink targets are left unchanged.

literalinclude

This adds :content-substitutions: and :path-substitutions: options to Sphinx’s built-in literalinclude directive.

Replace substitutions in the content of the included file:

.. literalinclude:: path/to/file.txt
   :content-substitutions:

Replace substitutions in the file path:

.. literalinclude:: path/to/|author|_file.txt
   :path-substitutions:

include

This adds :content-substitutions: and :path-substitutions: options to docutils’ built-in include directive.

Replace substitutions in the included source content before it is parsed:

.. include:: path/to/file.rst
   :content-substitutions:

Replace substitutions in the file path:

.. include:: path/to/|author|_file.txt
   :path-substitutions:

image

This adds a :path-substitutions: option to Sphinx’s built-in image directive.

Replace substitutions in the image path:

.. image:: path/to/|author|_diagram.png
   :path-substitutions:
   :alt: Diagram

code-block

This adds a :substitutions: option to Sphinx’s built-in code-block directive.

```{code-block} bash
   :substitutions:

   echo "|author| released version |release|"
```

As well as using |author|, you can also use {{author}}. This will respect the value of myst_sub_delimiters as set in conf.py.

Inline :substitution-code:

{substitution-code}`echo "|author| released version |release|"`

substitution-download

{substitution-download}`|author|'s manuscript <|author|_manuscript.txt>`

literalinclude

This adds :content-substitutions: and :path-substitutions: options to Sphinx’s built-in literalinclude directive.

Replace substitutions in the content of the included file:

```{literalinclude} path/to/file.txt
   :content-substitutions:
```

Replace substitutions in the file path:

```{literalinclude} path/to/|author|_file.txt
   :path-substitutions:
```

include

This adds a :path-substitutions: option to docutils’ built-in include directive.

Replace substitutions in the file path:

```{include} path/to/|author|_file.txt
   :path-substitutions:
```

image

This adds a :path-substitutions: option to Sphinx’s built-in image directive.

Replace substitutions in the image path:

```{image} path/to/|author|_diagram.png
   :path-substitutions:
   :alt: Diagram
```

Nested substitutions

myst_substitutions supports nested dictionaries and lists, which are flattened using dot notation.

Important: Substitution keys cannot contain dots (.), as dots are reserved for nested access notation. For example, {"key.with.dots": "value"} raises an exception.

Nested dictionaries:

"""Configuration for Sphinx."""

myst_substitutions = {
    "app": {
        "name": "MyApp",
        "version": "1.0.0",
    },
}

Usage in Markdown:

```{code-block} bash
   :substitutions:

   echo "Application: |app.name| version |app.version|"
```

Lists with index access:

"""Configuration for Sphinx."""

myst_substitutions = {
    "platforms": ["Linux", "Windows", "macOS"],
}

Usage:

```{code-block} bash
   :substitutions:

   echo "First platform: |platforms.0|"
   echo "Second platform: |platforms.1|"
```

Nested lists of dictionaries:

"""Configuration for Sphinx."""

myst_substitutions = {
    "releases": [
        {"version": "1.0", "codename": "Alpha"},
        {"version": "2.0", "codename": "Beta"},
    ],
}

Usage:

```{code-block} bash
   :substitutions:

   echo "First release: |releases.0.version| (|releases.0.codename|)"
   echo "Second release: |releases.1.version| (|releases.1.codename|)"
```

Complex nested structures:

"""Configuration for Sphinx."""

myst_substitutions = {
    "project": {
        "name": "MyProject",
        "contributors": [
            {"name": "Alice", "role": "dev"},
            {"name": "Bob", "role": "docs"},
        ],
    },
}

Usage:

```{code-block} bash
   :substitutions:

   echo "Project: |project.name|"
   echo "Developer: |project.contributors.0.name|"
   echo "Documentation: |project.contributors.1.name|"
```