---
id: sphinx-substitution-extensions
version: "2026.8.13.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# sphinx-substitution-extensions — Extensions for Sphinx which allow for substitutions.

License: permissive · Maintenance: active · Downloads: 253.8K/mo

## What it is and what it does

This package extends Sphinx with directives that perform variable substitution in documentation content. It works by registering new options (`:substitutions:`, `:content-substitutions:`, `:path-substitutions:`) on Sphinx's built-in directives like `code-block`, `literalinclude`, `include`, and `image`, plus adds new directives like `:substitution-code:` and `:substitution-download:`. Substitutions are defined in `conf.py` via `rst_prolog` for reStructuredText or `myst_substitutions` for MyST Markdown.

The package supports both reStructuredText and MyST Markdown syntax. Variables can be scoped globally (in `rst_prolog` or `myst_substitutions`) or per-document (in frontmatter for Markdown). By default, substitution flags must be added explicitly to each directive; a `substitutions_default_enabled` setting applies them automatically across all compatible directives. It depends on sphinx, docutils, myst-parser, and beartype, and requires Python 3.11 or later.

Use it for:

- Document version numbers and release dates that appear in code examples and download links without manual updates
- Replace author names, product names, or environment-specific values across code blocks and file paths in multi-author or multi-environment docs
- Generate dynamic file paths in `literalinclude` and `include` directives based on substitution variables
- Maintain consistent branding or configuration values in inline code snippets and hyperlink targets

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Adds substitution support to Sphinx directives, allowing variable replacement within code blocks, file paths, and other content during documentation builds.

Yes. Active maintenance, low install friction, no known vulnerabilities, and permissive MIT license. Install if you maintain Sphinx documentation with repeated variable values in code examples or file paths. Skip if your documentation is static and does not benefit from templating.

## Install

pip install sphinx-substitution-extensions
uv add sphinx-substitution-extensions
poetry add sphinx-substitution-extensions

## Installing sphinx-substitution-extensions

Before you install: Low friction install with a wheel distribution. Active maintenance as of 2026-08-14 with recent release. Depends on sphinx, docutils, myst-parser, and beartype—all standard documentation tooling.

License in practice: MIT license permits use in open-source and commercial projects with minimal restrictions; attribution required.

Quickstart:

pip install sphinx-substitution-extensions

# In conf.py:
extensions = ["sphinx_substitution_extensions"]
rst_prolog = """
.. |version| replace:: 1.0
.. |author| replace:: Jane
"""

# In your .rst file:
.. code-block:: shell
   :substitutions:

   echo "|author| released |version|"

Requires Python 3.11 or later and Sphinx 8.2.0 or later.

Verify before relying:

- Whether substitution syntax conflicts with existing Sphinx extensions in real projects
- Performance impact when substitutions_default_enabled is true on large documentation sets
- Exact scope of MyST Markdown support beyond the documented examples

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 253.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sphinx variable substitution, sphinx code block substitutions, sphinx template variables, sphinx dynamic content replacement, sphinx rst substitutions, sphinx markdown substitutions, sphinx literal include substitutions, sphinx-extension, documentation-tooling

[View on SkillFed](https://skillfed.io/packages/sphinx-substitution-extensions) · [View on PyPI](https://pypi.org/project/sphinx-substitution-extensions/)