Sphinx Substitution Extensions

2026.1.12 · active · verified Thu Apr 16

Sphinx Substitution Extensions enhances Sphinx documentation by enabling variable substitutions within standard directives like `code-block`, `literalinclude`, and `image`, and introduces an inline `substitution-code` role. It supports both reStructuredText (reST) and MyST Markdown syntax for defining and using substitutions. The project maintains a frequent release cadence, often with multiple updates per month, ensuring continuous improvements and compatibility.

Common errors

```
Substitutions inside Sphinx code blocks aren't replaced / Variable substitution not working properly in Sphinx
```
cause Sphinx's native `code-block` directive does not process reStructuredText substitutions by default, leading to placeholders like `|VAR|` or `{{VAR}}` appearing literally.

fix Ensure `sphinx_substitution_extensions` is enabled in `conf.py`. For reStructuredText, either add the `:substitutions:` option to the `code-block` directive (e.g., `.. code-block:: python :substitutions:`) or set `substitutions_default_enabled = True` in `conf.py`. For MyST Markdown, use the `{{VAR}}` syntax and ensure `:substitutions:` is present.
```
Sphinx error: 'sphinx_substitution_extensions' is not a Sphinx extension
```
cause The extension module `sphinx_substitution_extensions` could not be found or loaded by Sphinx. This typically means it was not installed or incorrectly added to the `extensions` list.

fix Run `pip install sphinx-substitution-extensions` to ensure the package is installed. Then, verify that `sphinx_substitution_extensions` is correctly listed as a string in the `extensions` list within your `conf.py` file.
```
Configuration error: 'sphinx-prompt' must be loaded before 'sphinx_substitution_extensions'
```
cause The `sphinx_substitution_extensions` library requires `sphinx-prompt` to be loaded first if both are used, due to how they interact or extend Sphinx's parsing. The order in the `extensions` list in `conf.py` is incorrect.

fix Modify your `conf.py` to ensure `sphinx-prompt` appears before `sphinx_substitution_extensions` in the `extensions` list. Example: `extensions = ['sphinx-prompt', 'sphinx_substitution_extensions', ...]`

Warnings

gotcha When integrating with `sphinx-prompt`, ensure `sphinx-prompt` is listed *before* `sphinx_substitution_extensions` in your `conf.py` extensions list to prevent conflicts or incorrect behavior.
Fix: In `conf.py`, set `extensions = ['sphinx-prompt', 'sphinx_substitution_extensions', ...]`.
gotcha Substitutions are not applied by default to Sphinx's built-in `code-block` or `literalinclude` directives. You must explicitly add the `:substitutions:`, `:content-substitutions:`, or `:path-substitutions:` flags, or enable substitutions globally.
Fix: Add `:substitutions:` (or `content-/path-substitutions`) to the directive, or set `substitutions_default_enabled = True` in your `conf.py` to apply them automatically to all relevant directives.
breaking This library explicitly states compatibility with Sphinx versions 8.2.0+ and Python 3.11+ in its latest GitHub README and PyPI classifiers, despite PyPI metadata stating `requires_python: >=3.10`. Using older Sphinx versions or Python 3.10 might lead to unexpected issues or errors.
Fix: Upgrade Sphinx to 8.2.0 or newer and ensure your Python environment is 3.11+.

Install

pip install sphinx-substitution-extensions Basic Installation
pip install sphinx-substitution-extensions[prompt] With sphinx-prompt integration

Imports

sphinx_substitution_extensions
```
extensions = [
    # other extensions...
    'sphinx_substitution_extensions',
]
```
Add to the `extensions` list in `conf.py` to enable the extension.

Quickstart

To quickly integrate `sphinx-substitution-extensions`, add it to your `extensions` list in `conf.py`. Define your substitutions using `rst_prolog` for reStructuredText files or `myst_substitutions` for MyST Markdown. Then, use the `|KEY|` syntax in reST or `{{KEY}}` in MyST within directives that support substitutions (like `code-block` with the `:substitutions:` flag) or with the inline `:substitution-code:` role. Setting `substitutions_default_enabled = True` in `conf.py` applies substitutions to code blocks and literal includes without explicit flags.

# conf.py
extensions = [
    'sphinx.ext.autodoc',
    'sphinx_substitution_extensions',
]

# Define substitutions for reStructuredText
rst_prolog = '''
.. |project_name| replace:: My Awesome Project
.. |version| replace:: 1.0.0
'''

# Optional: Enable substitutions by default for applicable directives
substitutions_default_enabled = True

# .rst file (e.g., index.rst)
# .. code-block:: python
#    print("Welcome to |project_name| version |version|!")

# .rst file (e.g., index.rst) - manual substitution flag
# .. code-block:: bash
#    :substitutions:
#
#    echo "Hello from |project_name|"

# .rst file (e.g., index.rst) - inline substitution
# :substitution-code:`echo "Installed version: |version|"`

# For MyST Markdown (if myst-parser is installed)
# myst_enable_extensions = ["substitution"]
# myst_substitutions = {
#     "project_name": "My Awesome Project",
#     "version": "1.0.0",
# }
#
# In a .md file:
# ```{code-block} bash
# :substitutions:
# echo "Hello from {{project_name}}"
# ```
#
# In a .md file - inline substitution:
# {substitution-code}`echo "Installed version: {{version}}"`

view raw JSON →