sphinx-substitution-extensions 2026.6.17

Extensions for Sphinx which allow for substitutions.

Sphinx Substitution Extensions

Extensions for Sphinx which allow substitutions within code blocks.

Contents

• Sphinx Substitution Extensions

  • Installation

  • rST setup

  • Using substitutions in rST documents

    • code-block

    • Inline :substitution-code:

    • substitution-download

    • literalinclude

    • image

  • MyST Markdown setup

  • Enabling substitutions by default

  • Using substitutions in MyST Markdown

    • code-block

    • Inline :substitution-code:

    • substitution-download

    • literalinclude

    • image

    • Nested substitutions

  • Credits

  • Contributing

Installation

Sphinx Substitution Extensions is compatible with Sphinx 8.2.0+ using Python 3.11+.

$ pip install Sphinx-Substitution-Extensions

rST setup

1. Add the following to conf.py to enable the extension:

"""Configuration for Sphinx."""

extensions = ["sphinxcontrib.spelling"]  # Example existing extensions

extensions += ["sphinx_substitution_extensions"]

2. Set the following variable in conf.py to define substitutions:

"""Configuration for Sphinx."""

rst_prolog = """
.. |release| replace:: 0.1
.. |author| replace:: Eleanor
"""

This will replace |release| in the new directives with 0.1, and |author| with Eleanor.

Using substitutions in rST documents

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>`

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:

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

MyST Markdown setup

1. Add sphinx_substitution_extensions to extensions in conf.py to enable the extension:

"""Configuration for Sphinx."""

extensions = ["myst_parser"]  # Example existing extensions

extensions += ["sphinx_substitution_extensions"]

2. Set the following variables in conf.py to define substitutions:

"""Configuration for Sphinx."""

myst_enable_extensions = ["substitution"]

myst_substitutions = {
    "release": "0.1",
    "author": "Eleanor",
}

This will replace |release| in the new directives with 0.1, and |author| with Eleanor.

Enabling substitutions by default

By default, you need to explicitly add the :substitutions: flag to code-block directives, and :content-substitutions: or :path-substitutions: flags to literalinclude directives.

If you want substitutions to be applied by default without needing these flags, you can set the following in conf.py:

"""Configuration for Sphinx."""

substitutions_default_enabled = True

When this is enabled:

• All code-block directives will have substitutions applied automatically

• All literalinclude directives will have both content and path substitutions applied automatically

You can disable substitutions for specific directives when the default is enabled:

.. code-block:: shell
   :nosubstitutions:

   echo "This |will| not be substituted"

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

.. literalinclude:: path/to/|literal|_file.txt
   :nopath-substitutions:

Using substitutions in MyST Markdown

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:
```

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|"
```

Credits

ClusterHQ Developers

This package is largely inspired by code written for Flocker by ClusterHQ. Developers of the relevant code include, at least, Jon Giddy and Tom Prince.

Contributing

See CONTRIBUTING.rst.