Include directive

README.rst

@@ -90,6 +90,18 @@ 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:
+
+.. code-block:: rst
+
+   .. include:: path/to/|author|_file.txt
+      :path-substitutions:
+
 ``image``
 ~~~~~~~~~
 
@@ -134,7 +146,7 @@ This will replace ``|release|`` in the new directives with ``0.1``, and ``|autho
 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.
+By default, you need to explicitly add the ``:substitutions:`` flag to ``code-block`` directives, and ``:path-substitutions:`` flags to ``literalinclude``, ``include``, and ``image`` directives (or ``:content-substitutions:`` for ``literalinclude``).
 
 If you want substitutions to be applied by default without needing these flags, you can set the following in ``conf.py``:
 
@@ -148,6 +160,8 @@ 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
+- All ``include`` directives will have path substitutions applied automatically
+- All ``image`` directives will have path substitutions applied automatically
 
 You can disable substitutions for specific directives when the default is enabled:
 
@@ -164,6 +178,12 @@ You can disable substitutions for specific directives when the default is enable
    .. literalinclude:: path/to/|literal|_file.txt
       :nopath-substitutions:
 
+   .. include:: path/to/|literal|_file.txt
+      :nopath-substitutions:
+
+   .. image:: path/to/|literal|_diagram.png
+      :nopath-substitutions:
+
 Using substitutions in MyST Markdown
 ------------------------------------
 
@@ -218,6 +238,19 @@ Replace substitutions in the file path:
       :path-substitutions:
    ```
 
+``include``
+~~~~~~~~~~~
+
+This adds a ``:path-substitutions:`` option to docutils' built-in `include`_ directive.
+
+Replace substitutions in the file path:
+
+.. code-block:: markdown
+
+   ```{include} path/to/|author|_file.txt
+      :path-substitutions:
+   ```
+
 ``image``
 ~~~~~~~~~
 
@@ -250,6 +283,7 @@ See `CONTRIBUTING.rst <./CONTRIBUTING.rst>`_.
    :target: https://github.com/adamtheturtle/sphinx-substitution-extensions/actions
 .. _code-block: http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block
 .. _literalinclude: http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude
+.. _include: https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment
 .. _image: http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-image
 .. |PyPI| image:: https://badge.fury.io/py/Sphinx-Substitution-Extensions.svg
    :target: https://badge.fury.io/py/Sphinx-Substitution-Extensions

sample/source/index.rst

@@ -62,6 +62,15 @@ Path substitutions
    .. literalinclude:: |author|.txt
       :path-substitutions:
 
+``include``
+-----------
+
+Path substitutions
+~~~~~~~~~~~~~~~~~~
+
+.. include:: |author|.txt
+   :path-substitutions:
+
 ``image``
 ---------
 

sample/source/markdown_sample.md

@@ -125,6 +125,27 @@ Inline ``:substitution-code:``
 :path-substitutions:
 ```
 
+``include``
+-----------
+
+### Path substitutions
+
+```{code-block} markdown
+
+    ```{include} {{author}}.txt
+    :path-substitutions:
+    ```
+```
+
+<!-- Note: The actual include directive example is commented out due to
+issues with MyST parsing contexts. See the rST sample for a working example. -->
+
+<!--
+```{include} {{author}}.txt
+:path-substitutions:
+```
+-->
+
 ``image``
 ---------
 

src/sphinx_substitution_extensions/__init__.py

@@ -15,6 +15,7 @@
 )
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.directives.images import Image
+from docutils.parsers.rst.directives.misc import Include
 from docutils.parsers.rst.roles import code_role
 from docutils.parsers.rst.states import Inliner
 from docutils.statemachine import StringList
@@ -353,6 +354,56 @@ def run(self) -> list[Node]:
         return nodes_list
 
 
+@beartype
+class SubstitutionInclude(Include):
+    """
+    Similar to Include but replaces placeholders with variables in the path.
+    """
+
+    option_spec: ClassVar[OptionSpec] = Include.option_spec.copy()
+    option_spec[PATH_SUBSTITUTION_OPTION_NAME] = directives.flag
+    option_spec[NO_PATH_SUBSTITUTION_OPTION_NAME] = directives.flag
+
+    def run(self) -> list[Node]:
+        """
+        Replace placeholders with given variables in the file path.
+        """
+        env = self.state.document.settings.env
+
+        if env is not None:
+            config = env.config
+
+            should_apply_path_substitutions = _should_apply_substitutions(
+                options=self.options,
+                config=config,
+                yes_flag=PATH_SUBSTITUTION_OPTION_NAME,
+                no_flag=NO_PATH_SUBSTITUTION_OPTION_NAME,
+            )
+
+            if should_apply_path_substitutions:
+                substitution_defs = _get_substitution_defs(
+                    env=env,
+                    config=config,
+                    substitution_defs=self.state.document.substitution_defs,
+                )
+
+                delimiter_pairs = _get_delimiter_pairs(
+                    env=env,
+                    config=config,
+                )
+
+                for argument_index, argument in enumerate(
+                    iterable=self.arguments
+                ):
+                    self.arguments[argument_index] = _apply_substitutions(
+                        text=argument,
+                        substitution_defs=substitution_defs,
+                        delimiter_pairs=delimiter_pairs,
+                    )
+
+        return list(super().run())
+
+
 @beartype
 class SubstitutionImage(Image):
     """
@@ -484,6 +535,10 @@ def setup(app: Sphinx) -> ExtensionMetadata:
         name="literalinclude",
         directive=SubstitutionLiteralInclude,
     )
+    directives.register_directive(
+        name="include",
+        directive=SubstitutionInclude,
+    )
     directives.register_directive(
         name="image",
         directive=SubstitutionImage,