{"library":"sphinx-substitution-extensions","title":"Sphinx Substitution Extensions","type":"library","description":"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.","language":"python","status":"active","last_verified":"Sun May 17","install":{"commands":["pip install sphinx-substitution-extensions","pip install sphinx-substitution-extensions[prompt]"],"cli":null},"imports":["extensions = [\n    # other extensions...\n    'sphinx_substitution_extensions',\n]"],"auth":{"required":false,"env_vars":[]},"links":{"homepage":null,"github":"https://github.com/adamtheturtle/sphinx-substitution-extensions","docs":null,"changelog":null,"pypi":"https://pypi.org/project/sphinx-substitution-extensions/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null},"quickstart":{"code":"# conf.py\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx_substitution_extensions',\n]\n\n# Define substitutions for reStructuredText\nrst_prolog = '''\n.. |project_name| replace:: My Awesome Project\n.. |version| replace:: 1.0.0\n'''\n\n# Optional: Enable substitutions by default for applicable directives\nsubstitutions_default_enabled = True\n\n# .rst file (e.g., index.rst)\n# .. code-block:: python\n#    print(\"Welcome to |project_name| version |version|!\")\n\n# .rst file (e.g., index.rst) - manual substitution flag\n# .. code-block:: bash\n#    :substitutions:\n#\n#    echo \"Hello from |project_name|\"\n\n# .rst file (e.g., index.rst) - inline substitution\n# :substitution-code:`echo \"Installed version: |version|\"`\n\n# For MyST Markdown (if myst-parser is installed)\n# myst_enable_extensions = [\"substitution\"]\n# myst_substitutions = {\n#     \"project_name\": \"My Awesome Project\",\n#     \"version\": \"1.0.0\",\n# }\n#\n# In a .md file:\n# ```{code-block} bash\n# :substitutions:\n# echo \"Hello from {{project_name}}\"\n# ```\n#\n# In a .md file - inline substitution:\n# {substitution-code}`echo \"Installed version: {{version}}\"`\n","lang":"python","description":"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.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":{"tag":null,"tag_description":null,"last_tested":"2026-05-17","installed_version":"2022.2.16","pypi_latest":"2026.1.12","is_stale":true,"summary":{"python_range":"3.10–3.9","success_rate":100,"avg_install_s":6,"avg_import_s":null,"wheel_type":"wheel"},"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"sphinx-substitution-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"105.6M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"prompt","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"105.6M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"sphinx-substitution-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":6.2,"import_time_s":null,"mem_mb":null,"disk_size":"107M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"prompt","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":6.1,"import_time_s":null,"mem_mb":null,"disk_size":"107M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"sphinx-substitution-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"115.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"prompt","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"115.8M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"sphinx-substitution-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":6.2,"import_time_s":null,"mem_mb":null,"disk_size":"117M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"prompt","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":6.3,"import_time_s":null,"mem_mb":null,"disk_size":"117M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"sphinx-substitution-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"106.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"prompt","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"106.6M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"sphinx-substitution-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":5.8,"import_time_s":null,"mem_mb":null,"disk_size":"108M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"prompt","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":6,"import_time_s":null,"mem_mb":null,"disk_size":"108M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"sphinx-substitution-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"106.4M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"prompt","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"106.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"sphinx-substitution-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":5.6,"import_time_s":null,"mem_mb":null,"disk_size":"108M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"prompt","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":5.7,"import_time_s":null,"mem_mb":null,"disk_size":"108M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"sphinx-substitution-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"91.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"prompt","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"91.6M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"sphinx-substitution-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":6.3,"import_time_s":null,"mem_mb":null,"disk_size":"92M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"prompt","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":6.1,"import_time_s":null,"mem_mb":null,"disk_size":"92M"}]}}