Add recursive argument to include-markdown directive (#218)

Author: mondeja

README.md

@@ -155,6 +155,9 @@ content to include.
 - <a name="include-markdown_trailing-newlines" href="#include-markdown_trailing-newlines">#</a>
   **trailing-newlines** (_true_): When this option is disabled, the trailing newlines
   found in the content to include are stripped. Possible values are `true` and `false`.
+- <a name="include-markdown_recursive" href="#include-markdown_recursive">#</a>
+  **recursive** (_true_): When this option is disabled, included files are not
+  processed for recursive includes. Possible values are `true` and `false`.
 - <a name="include-markdown_encoding" href="#include-markdown_encoding">#</a>
   **encoding** (_utf-8_): Specify the encoding of the included file.
   If not defined `utf-8` will be used.
@@ -243,12 +246,12 @@ Includes the content of a file or a group of files.
 - <a name="include_trailing-newlines" href="#include_trailing-newlines">#</a>
   **trailing-newlines** (_true_): When this option is disabled, the trailing newlines
   found in the content to include are stripped. Possible values are `true` and `false`.
+- <a name="include_recursive" href="#include_recursive">#</a>
+  **recursive** (_true_): When this option is disabled, included files are not
+  processed for recursive includes. Possible values are `true` and `false`.
 - <a name="include_encoding" href="#include_encoding">#</a>
   **encoding** (_utf-8_): Specify the encoding of the included file.
   If not defined `utf-8` will be used.
-- <a name="recursive" href="#include_recursive">#</a>
-  **recursive** (_true_): When this option is disabled, included files are not
-  processed for recursive includes. Possible values are `true` and `false`.
 
 ##### Examples
 
@@ -275,8 +278,9 @@ Includes the content of a file or a group of files.
 
 ## Acknowledgment
 
-- Joe Rickerby and contributors for
-  [giving me the permissions][cibuildwheel-470] to separate this plugin from the
+- [Joe Rickerby] and [contributors] for
+  [giving me the permissions][cibuildwheel-470] to
+  [separate this plugin][cibuildwheel-475] from the
   documentation of [cibuildwheel][cibuildwheel-repo-link].
 
 [Bash wildcard globs]: https://facelessuser.github.io/wcmatch/glob/#syntax
@@ -293,7 +297,10 @@ Includes the content of a file or a group of files.
 [license-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/LICENSE
 [platformdirs]: https://pypi.org/project/platformdirs/
 [cibuildwheel-470]: https://github.com/pypa/cibuildwheel/issues/470
+[cibuildwheel-475]: https://github.com/pypa/cibuildwheel/pull/475
 [cibuildwheel-repo-link]: https://github.com/pypa/cibuildwheel
 [es-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/es/README.md
 [fr-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/fr/README.md
 [`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
+[Joe Rickerby]: https://github.com/joerick
+[contributors]: https://github.com/mondeja/mkdocs-include-markdown-plugin/graphs/contributors

locale/es/README.md

@@ -144,6 +144,10 @@ href="#include-markdown_trailing-newlines">#</a> **trailing-newlines**
 (*true*): Cuando esta opción está deshabilitada, los saltos de línea finales que
 se encuentran en el contenido a incluir se eliminan. Los valores posibles son
 `true` y `false`.
+- <a name="include-markdown_recursive" href="#include-markdown_recursive">#</a>
+**recursive** (*true*): Cuando esta opción está deshabilitada, los archivos
+incluidos no son procesados para incluir de forma recursiva. Los valores
+posibles son `true` y `false`.
 - <a name="include-markdown_encoding" href="#include-markdown_encoding">#</a>
 **encoding** (*utf-8*): Especifica la codificación del archivo incluído. Si no
 se define, se usará `utf-8`.
@@ -234,13 +238,13 @@ globs para incluir múltiples archivos.
 **trailing-newlines** (*true*): Cuando esta opción está deshabilitada, los
 saltos de línea finales que se encuentran en el contenido a incluir se eliminan.
 Los valores posibles son `true` y `false`.
+- <a name="include_recursive" href="#include_recursive">#</a> **recursive**
+(*true*): Cuando esta opción está deshabilitada, los archivos incluidos no son
+procesados para incluir de forma recursiva. Los valores posibles son `true` y
+`false`.
 - <a name="include_encoding" href="#include_encoding">#</a> **encoding**
 (*utf-8*): Especifica la codificación del archivo incluído. Si no se define,
 se usará `utf-8`.
-- <a name="recursive" href="#include_recursive">#</a> **recursive** (*true*):
-Cuando esta opción está deshabilitada, los archivos incluidos no son
-procesados para incluir de forma recursiva. Los valores posibles son `true` y
-`false`.
 
 ##### Ejemplos
 
@@ -267,8 +271,8 @@ procesados para incluir de forma recursiva. Los valores posibles son `true` y
 
 ## Agradecimiento
 
-- Joe Rickerby y contribuidores por [darme los permisos][cibuildwheel-470] para
-separar este plugin de la documentación de
+- [Joe Rickerby] y [contribuidores] por [darme los permisos][cibuildwheel-470]
+para [separar este plugin][cibuildwheel-475] de la documentación de
 [cibuildwheel][cibuildwheel-repo-link].
 
 [Patrones glob de Bash]: https://facelessuser.github.io/wcmatch/glob/#syntax
@@ -282,7 +286,10 @@ separar este plugin de la documentación de
 [license-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/LICENSE
 [platformdirs]: https://pypi.org/project/platformdirs/
 [cibuildwheel-470]: https://github.com/pypa/cibuildwheel/issues/470
+[cibuildwheel-475]: https://github.com/pypa/cibuildwheel/pull/475
 [cibuildwheel-repo-link]: https://github.com/pypa/cibuildwheel
 [es-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/es/README.md
 [fr-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/fr/README.md
 [`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
+[Joe Rickerby]: https://github.com/joerick
+[contribuidores]: https://github.com/mondeja/mkdocs-include-markdown-plugin/graphs/contributors

locale/es/README.md.po

@@ -31,13 +31,13 @@ msgid "Acknowledgment"
 msgstr "Agradecimiento"
 
 msgid ""
-"Joe Rickerby and contributors for [giving me the "
-"permissions][cibuildwheel-470] to separate this plugin from the "
-"documentation of [cibuildwheel][cibuildwheel-repo-link]."
+"[Joe Rickerby] and [contributors] for [giving me the "
+"permissions][cibuildwheel-470] to [separate this plugin][cibuildwheel-475] "
+"from the documentation of [cibuildwheel][cibuildwheel-repo-link]."
 msgstr ""
-"Joe Rickerby y contribuidores por [darme los permisos][cibuildwheel-470] "
-"para separar este plugin de la documentación de [cibuildwheel][cibuildwheel-"
-"repo-link]."
+"[Joe Rickerby] y [contribuidores] por [darme los permisos][cibuildwheel-470]"
+" para [separar este plugin][cibuildwheel-475] de la documentación de "
+"[cibuildwheel][cibuildwheel-repo-link]."
 
 msgid ""
 "[pypi-version-badge-link]: https://img.shields.io/pypi/v/mkdocs-include-"
@@ -408,11 +408,35 @@ msgid "[pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin"
 msgstr "[pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin"
 
 msgid ""
-"<a name=\"recursive\" href=\"#include_recursive\">#</a> **recursive** "
-"(*true*): When this option is disabled, included files are not processed for"
-" recursive includes. Possible values are `true` and `false`."
+"<a name=\"include_recursive\" href=\"#include_recursive\">#</a> "
+"**recursive** (*true*): When this option is disabled, included files are not"
+" processed for recursive includes. Possible values are `true` and `false`."
 msgstr ""
-"<a name=\"recursive\" href=\"#include_recursive\">#</a> **recursive** "
-"(*true*): Cuando esta opción está deshabilitada, los archivos incluidos no "
-"son procesados para incluir de forma recursiva. Los valores posibles son "
-"`true` y `false`."
+"<a name=\"include_recursive\" href=\"#include_recursive\">#</a> "
+"**recursive** (*true*): Cuando esta opción está deshabilitada, los archivos "
+"incluidos no son procesados para incluir de forma recursiva. Los valores "
+"posibles son `true` y `false`."
+
+msgid ""
+"<a name=\"include-markdown_recursive\" href=\"#include-"
+"markdown_recursive\">#</a> **recursive** (*true*): When this option is "
+"disabled, included files are not processed for recursive includes. Possible "
+"values are `true` and `false`."
+msgstr ""
+"<a name=\"include-markdown_recursive\" href=\"#include-"
+"markdown_recursive\">#</a> **recursive** (*true*): Cuando esta opción está "
+"deshabilitada, los archivos incluidos no son procesados para incluir de "
+"forma recursiva. Los valores posibles son `true` y `false`."
+
+msgid "[Joe Rickerby]: https://github.com/joerick"
+msgstr "[Joe Rickerby]: https://github.com/joerick"
+
+msgid ""
+"[contributors]: https://github.com/mondeja/mkdocs-include-markdown-"
+"plugin/graphs/contributors"
+msgstr ""
+"[contribuidores]: https://github.com/mondeja/mkdocs-include-markdown-"
+"plugin/graphs/contributors"
+
+msgid "[cibuildwheel-475]: https://github.com/pypa/cibuildwheel/pull/475"
+msgstr "[cibuildwheel-475]: https://github.com/pypa/cibuildwheel/pull/475"

locale/fr/README.md

@@ -144,6 +144,10 @@ href="#include-markdown_trailing-newlines">#</a> **trailing-newlines**
 (*true*): Lorsque cette option est désactivée, les nouvelles lignes de fin
 trouvées dans le contenu à inclure sont supprimées. Les valeurs possibles sont
 `true` et `false`.
+- <a name="include-markdown_recursive" href="#include-markdown_recursive">#</a>
+**recursive** (*true*): Lorsque cette option est désactivée, les fichiers
+inclus ne sont pas traités pour des inclusions récursives. Les valeurs possibles
+sont `true` et `false`.
 - <a name="include-markdown_encoding" href="#include-markdown_encoding">#</a>
 **encoding** (*utf-8*): Spécifiez l'encodage du fichier inclus. S'il n'est pas
 défini, `utf-8` sera utilisé.
@@ -233,12 +237,13 @@ passage de globs pour inclure plusieurs fichiers.
 **trailing-newlines** (*true*): Lorsque cette option est désactivée, les
 nouvelles lignes de fin trouvées dans le contenu à inclure sont supprimées. Les
 valeurs possibles sont `true` et `false`.
+- <a name="include_recursive" href="#include_recursive">#</a> **recursive**
+(*true*): Lorsque cette option est désactivée, les fichiers inclus ne sont pas
+traités pour des inclusions récursives. Les valeurs possibles sont `true` et
+`false`.
 - <a name="include_encoding" href="#include_encoding">#</a> **encoding**
 (*utf-8*): Spécifiez l'encodage du fichier inclus. S'il n'est pas défini,
 `utf-8` sera utilisé.
-- <a name="recursive" href="#include_recursive">#</a> **recursive** (*true*):
-Lorsque cette option est désactivée, les fichiers inclus ne sont pas traités
-pour des inclusions récursives. Les valeurs possibles sont `true` et `false`.
 
 ##### Exemples
 
@@ -265,9 +270,9 @@ pour des inclusions récursives. Les valeurs possibles sont `true` et `false`.
 
 ## Reconnaissance
 
-- Joe Rickerby et des contributeurs pour [m'avoir donné les
-autorisations][cibuildwheel-470] pour séparer ce plugin de la documentation de
-[cibuildwheel][cibuildwheel-repo-link].
+- [Joe Rickerby] et [des contributeurs] pour [m'avoir donné les
+autorisations][cibuildwheel-470] pour [séparer ce plugin][cibuildwheel-475] de
+la documentation de [cibuildwheel][cibuildwheel-repo-link].
 
 [Globs génériques Bash]: https://facelessuser.github.io/wcmatch/glob/#syntax
 [pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin
@@ -280,7 +285,10 @@ autorisations][cibuildwheel-470] pour séparer ce plugin de la documentation de
 [license-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/LICENSE
 [platformdirs]: https://pypi.org/project/platformdirs/
 [cibuildwheel-470]: https://github.com/pypa/cibuildwheel/issues/470
+[cibuildwheel-475]: https://github.com/pypa/cibuildwheel/pull/475
 [cibuildwheel-repo-link]: https://github.com/pypa/cibuildwheel
 [es-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/es/README.md
 [fr-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/fr/README.md
 [`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
+[Joe Rickerby]: https://github.com/joerick
+[des contributeurs]: https://github.com/mondeja/mkdocs-include-markdown-plugin/graphs/contributors

locale/fr/README.md.po

@@ -44,13 +44,13 @@ msgid "Acknowledgment"
 msgstr "Reconnaissance"
 
 msgid ""
-"Joe Rickerby and contributors for [giving me the "
-"permissions][cibuildwheel-470] to separate this plugin from the "
-"documentation of [cibuildwheel][cibuildwheel-repo-link]."
+"[Joe Rickerby] and [contributors] for [giving me the "
+"permissions][cibuildwheel-470] to [separate this plugin][cibuildwheel-475] "
+"from the documentation of [cibuildwheel][cibuildwheel-repo-link]."
 msgstr ""
-"Joe Rickerby et des contributeurs pour [m'avoir donné les "
-"autorisations][cibuildwheel-470] pour séparer ce plugin de la documentation "
-"de [cibuildwheel][cibuildwheel-repo-link]."
+"[Joe Rickerby] et [des contributeurs] pour [m'avoir donné les "
+"autorisations][cibuildwheel-470] pour [séparer ce plugin][cibuildwheel-475] "
+"de la documentation de [cibuildwheel][cibuildwheel-repo-link]."
 
 msgid ""
 "[pypi-version-badge-link]: https://img.shields.io/pypi/v/mkdocs-include-"
@@ -406,11 +406,35 @@ msgid "[pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin"
 msgstr "[pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin"
 
 msgid ""
-"<a name=\"recursive\" href=\"#include_recursive\">#</a> **recursive** "
-"(*true*): When this option is disabled, included files are not processed for"
-" recursive includes. Possible values are `true` and `false`."
+"<a name=\"include_recursive\" href=\"#include_recursive\">#</a> "
+"**recursive** (*true*): When this option is disabled, included files are not"
+" processed for recursive includes. Possible values are `true` and `false`."
 msgstr ""
-"<a name=\"recursive\" href=\"#include_recursive\">#</a> **recursive** "
-"(*true*): Lorsque cette option est désactivée, les fichiers inclus ne sont "
-"pas traités pour des inclusions récursives. Les valeurs possibles sont "
-"`true` et `false`."
+"<a name=\"include_recursive\" href=\"#include_recursive\">#</a> "
+"**recursive** (*true*): Lorsque cette option est désactivée, les fichiers "
+"inclus ne sont pas traités pour des inclusions récursives. Les valeurs "
+"possibles sont `true` et `false`."
+
+msgid ""
+"<a name=\"include-markdown_recursive\" href=\"#include-"
+"markdown_recursive\">#</a> **recursive** (*true*): When this option is "
+"disabled, included files are not processed for recursive includes. Possible "
+"values are `true` and `false`."
+msgstr ""
+"<a name=\"include-markdown_recursive\" href=\"#include-"
+"markdown_recursive\">#</a> **recursive** (*true*): Lorsque cette option est "
+"désactivée, les fichiers inclus ne sont pas traités pour des inclusions "
+"récursives. Les valeurs possibles sont `true` et `false`."
+
+msgid "[Joe Rickerby]: https://github.com/joerick"
+msgstr "[Joe Rickerby]: https://github.com/joerick"
+
+msgid ""
+"[contributors]: https://github.com/mondeja/mkdocs-include-markdown-"
+"plugin/graphs/contributors"
+msgstr ""
+"[des contributeurs]: https://github.com/mondeja/mkdocs-include-markdown-"
+"plugin/graphs/contributors"
+
+msgid "[cibuildwheel-475]: https://github.com/pypa/cibuildwheel/pull/475"
+msgstr "[cibuildwheel-475]: https://github.com/pypa/cibuildwheel/pull/475"

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs-include-markdown-plugin"
-version = "6.1.2"
+version = "6.2.0"
 description = "Mkdocs Markdown includer plugin."
 readme = "README.md"
 license = "Apache-2.0"

src/mkdocs_include_markdown_plugin/directive.py

@@ -110,9 +110,7 @@ def str_arg(arg: str) -> re.Pattern[str]:
     )
 }
 
-INCLUDE_MARKDOWN_DIRECTIVE_ARGS = {
-    key for key in ARGUMENT_REGEXES if key != 'recursive'
-}
+INCLUDE_MARKDOWN_DIRECTIVE_ARGS = set(ARGUMENT_REGEXES)
 
 
 def warn_invalid_directive_arguments(

src/mkdocs_include_markdown_plugin/event.py

@@ -379,7 +379,7 @@ def found_include_markdown_tag(  # noqa: PLR0912, PLR0915
             [
                 'rewrite-relative-urls', 'comments',
                 'preserve-includer-indent', 'dedent',
-                'trailing-newlines',
+                'trailing-newlines', 'recursive',
             ],
             defaults,
             arguments_string,
@@ -498,16 +498,17 @@ def found_include_markdown_tag(  # noqa: PLR0912, PLR0915
                         expected_but_any_found[i] = False
 
             # nested includes
-            new_text_to_include = get_file_content(
-                new_text_to_include,
-                file_path,
-                docs_dir,
-                tags,
-                defaults,
-                settings,
-                files_watcher=files_watcher,
-                http_cache=http_cache,
-            )
+            if bool_options['recursive'].value:
+                new_text_to_include = get_file_content(
+                    new_text_to_include,
+                    file_path,
+                    docs_dir,
+                    tags,
+                    defaults,
+                    settings,
+                    files_watcher=files_watcher,
+                    http_cache=http_cache,
+                )
 
             # trailing newlines right stripping
             if not bool_options['trailing-newlines'].value:

tests/test_unit/test_nested_includes.py

@@ -251,6 +251,32 @@
             [],
             id='include-recursive=false',
         ),
+        # recursive inclusion disabled with `include-markdown` directive
+        pytest.param(
+            '''# Header
+
+{%
+  include-markdown "{filepath}"
+  recursive=false
+  comments=false
+%}''',
+            '''# Header 2
+
+{% include-markdown "{filepath}" %}
+''',
+            '''# Header 3
+
+This content must not be included.
+''',
+            '''# Header
+
+# Header 2
+
+{% include-markdown "{filepath}" %}
+''',
+            [],
+            id='include-markdown-recursive=false',
+        ),
     ),
 )
 def test_nested_include(