mkdocs-include-markdown-plugin 6.1.1__tar.gz → 6.2.0__tar.gz

{mkdocs_include_markdown_plugin-6.1.1 → mkdocs_include_markdown_plugin-6.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: mkdocs-include-markdown-plugin
-Version: 6.1.1
+Version: 6.2.0
 Summary: Mkdocs Markdown includer plugin.
 Project-URL: Source, https://github.com/mondeja/mkdocs-include-markdown-plugin
 Project-URL: Documentation, https://github.com/mondeja/mkdocs-include-markdown-plugin#documentation
@@ -190,6 +190,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.
@@ -212,42 +215,42 @@ content to include.
 
 ```jinja
 {%
-   include-markdown "../README.md"
-   start="<!--intro-start-->"
-   end="<!--intro-end-->"
+    include-markdown "../README.md"
+    start="<!--intro-start-->"
+    end="<!--intro-end-->"
 %}
 ```
 
 ```jinja
 {%
-   include-markdown 'includes/header.md'
-   start='<!--\n\ttable-start\n-->'
-   end='<!--\n\ttable-end\n-->'
-   rewrite-relative-urls=false
-   comments=false
+    include-markdown 'includes/header.md'
+    start='<!--\n\ttable-start\n-->'
+    end='<!--\n\ttable-end\n-->'
+    rewrite-relative-urls=false
+    comments=false
 %}
 ```
 
 ```jinja
 {%
-   include-markdown "includes/header.md"
-   heading-offset=1
+    include-markdown "includes/header.md"
+    heading-offset=1
 %}
 ```
 
 ```jinja
 {%
-   include-markdown "../LICENSE*"
-   start="<!--license \"start\" -->"
-   end='<!--license "end" -->'
-   exclude="../*.rst"
+    include-markdown "../LICENSE*"
+    start="<!--license \"start\" -->"
+    end='<!--license "end" -->'
+    exclude="../*.rst"
 %}
 ```
 
 ```jinja
 {%
-   include-markdown "**"
-   exclude="./{index,LICENSE}.md"
+    include-markdown "**"
+    exclude="./{index,LICENSE}.md"
 %}
 ```
 
@@ -278,12 +281,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
 
@@ -295,23 +298,24 @@ Includes the content of a file or a group of files.
 
 ```jinja
     {%
-      include "../examples.md"
-      start="~~~yaml"
-      end="~~~\n"
+        include "../examples.md"
+        start="~~~yaml"
+        end="~~~\n"
     %}
 ```
 
 ```jinja
 {%
-   include '**'
-   exclude='./*.md'
+    include '**'
+    exclude='./*.md'
 %}
 ```
 
 ## 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
@@ -328,7 +332,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

{mkdocs_include_markdown_plugin-6.1.1 → mkdocs_include_markdown_plugin-6.2.0}/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.
@@ -177,42 +180,42 @@ content to include.
 
 ```jinja
 {%
-   include-markdown "../README.md"
-   start="<!--intro-start-->"
-   end="<!--intro-end-->"
+    include-markdown "../README.md"
+    start="<!--intro-start-->"
+    end="<!--intro-end-->"
 %}
 ```
 
 ```jinja
 {%
-   include-markdown 'includes/header.md'
-   start='<!--\n\ttable-start\n-->'
-   end='<!--\n\ttable-end\n-->'
-   rewrite-relative-urls=false
-   comments=false
+    include-markdown 'includes/header.md'
+    start='<!--\n\ttable-start\n-->'
+    end='<!--\n\ttable-end\n-->'
+    rewrite-relative-urls=false
+    comments=false
 %}
 ```
 
 ```jinja
 {%
-   include-markdown "includes/header.md"
-   heading-offset=1
+    include-markdown "includes/header.md"
+    heading-offset=1
 %}
 ```
 
 ```jinja
 {%
-   include-markdown "../LICENSE*"
-   start="<!--license \"start\" -->"
-   end='<!--license "end" -->'
-   exclude="../*.rst"
+    include-markdown "../LICENSE*"
+    start="<!--license \"start\" -->"
+    end='<!--license "end" -->'
+    exclude="../*.rst"
 %}
 ```
 
 ```jinja
 {%
-   include-markdown "**"
-   exclude="./{index,LICENSE}.md"
+    include-markdown "**"
+    exclude="./{index,LICENSE}.md"
 %}
 ```
 
@@ -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
 
@@ -260,23 +263,24 @@ Includes the content of a file or a group of files.
 
 ```jinja
     {%
-      include "../examples.md"
-      start="~~~yaml"
-      end="~~~\n"
+        include "../examples.md"
+        start="~~~yaml"
+        end="~~~\n"
     %}
 ```
 
 ```jinja
 {%
-   include '**'
-   exclude='./*.md'
+    include '**'
+    exclude='./*.md'
 %}
 ```
 
 ## 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

{mkdocs_include_markdown_plugin-6.1.1 → mkdocs_include_markdown_plugin-6.2.0}/pyproject.toml

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

{mkdocs_include_markdown_plugin-6.1.1 → mkdocs_include_markdown_plugin-6.2.0}/src/mkdocs_include_markdown_plugin/directive.py

@@ -12,6 +12,7 @@ from mkdocs.exceptions import PluginError
 from wcmatch import glob
 
 from mkdocs_include_markdown_plugin import process
+from mkdocs_include_markdown_plugin.logger import logger
 
 
 @dataclass
@@ -21,7 +22,7 @@ class DirectiveBoolArgument:  # noqa: D101
 
 
 if TYPE_CHECKING:
-    from typing import TypedDict
+    from typing import Literal, TypedDict
 
     DirectiveBoolArgumentsDict = dict[str, DirectiveBoolArgument]
 
@@ -44,8 +45,8 @@ if TYPE_CHECKING:
 GLOB_FLAGS = glob.NEGATE | glob.EXTGLOB | glob.GLOBSTAR | glob.BRACE
 RE_ESCAPED_PUNCTUATION = re.escape(string.punctuation)
 
-DOUBLE_QUOTED_STR_RE = r'([^"]|(?<=\\)["])+'
-SINGLE_QUOTED_STR_RE = r"([^']|(?<=\\)['])+"
+DOUBLE_QUOTED_STR_RE = r'([^"]|(?<=\\)")+'
+SINGLE_QUOTED_STR_RE = r"([^']|(?<=\\)')+"
 
 # In the following regular expression, the substrings "$OPENING_TAG"
 # and "$CLOSING_TAG" will be replaced by the effective opening and
@@ -103,6 +104,38 @@ ARGUMENT_REGEXES = {
     'heading-offset': arg('heading-offset'),
 }
 
+INCLUDE_DIRECTIVE_ARGS = {
+    key for key in ARGUMENT_REGEXES if key not in (
+        'rewrite-relative-urls', 'heading-offset', 'comments',
+    )
+}
+
+INCLUDE_MARKDOWN_DIRECTIVE_ARGS = set(ARGUMENT_REGEXES)
+
+
+def warn_invalid_directive_arguments(
+    arguments_string: str,
+    directive_lineno: int,
+    directive: Literal['include', 'include-markdown'],
+    page_src_path: str | None,
+    docs_dir: str,
+) -> None:
+    """Warns about the invalid arguments passed to a directive."""
+    arg_re = re.compile(rf'[\w-]*=[{RE_ESCAPED_PUNCTUATION}\w]*')
+    valid_args = (
+        INCLUDE_DIRECTIVE_ARGS if directive == 'include'
+        else INCLUDE_MARKDOWN_DIRECTIVE_ARGS
+    )
+    for arg_value in re.findall(arg_re, arguments_string):
+        if arg_value.split('=', 1)[0] not in valid_args:
+            location = process.file_lineno_message(
+                page_src_path, docs_dir, directive_lineno,
+            )
+            logger.warning(
+                f"Invalid argument '{arg_value}' in"
+                f" '{directive}' directive at {location}. Ignoring...",
+            )
+
 
 def parse_filename_argument(
         match: re.Match[str],

{mkdocs_include_markdown_plugin-6.1.1 → mkdocs_include_markdown_plugin-6.2.0}/src/mkdocs_include_markdown_plugin/event.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import html
-import logging
 import os
 import re
 import textwrap
@@ -23,12 +22,14 @@ from mkdocs_include_markdown_plugin.directive import (
     parse_string_argument,
     resolve_file_paths_to_exclude,
     resolve_file_paths_to_include,
+    warn_invalid_directive_arguments,
 )
 from mkdocs_include_markdown_plugin.files_watcher import FilesWatcher
+from mkdocs_include_markdown_plugin.logger import logger
 
 
 if TYPE_CHECKING:
-    from typing import TypedDict
+    from typing import Literal, TypedDict
 
     from mkdocs.structure.pages import Page
 
@@ -43,49 +44,26 @@ if TYPE_CHECKING:
     )
 
 
-@dataclass
-class Settings:  # noqa: D101
-    exclude: list[str] | None
-
-
-# TODO: when Mkdocs < 1.5.0 support is dropped, use
-# mkdocs.plugin.get_plugin_logger
-logger = logging.getLogger('mkdocs.plugins.include_markdown')
-
+# Placeholders (taken from Python-Markdown)
+STX = '\u0002'
+''' "Start of Text" marker for placeholder templates. '''
+ETX = '\u0003'
+''' "End of Text" marker for placeholder templates. '''
+INLINE_PLACEHOLDER_PREFIX = f'{STX}klzzwxh:'
 
-def lineno_from_content_start(content: str, start: int) -> int:
-    """Return the line number of the first line of ``start`` in ``content``."""
-    return content[:start].count('\n') + 1
 
-
-def safe_os_path_relpath(path: str, start: str) -> str:
-    """Return the relative path of a file from a start directory.
-
-    Safe version of `os.path.relpath` that catches `ValueError` exceptions
-    on Windows and returns the original path in case of error.
-    On Windows, `ValueError` is raised when `path` and `start` are on
-    different drives.
-    """
-    if os.name != 'nt':  # pragma: nt no cover
-        return os.path.relpath(path, start)
-    try:  # pragma: nt cover
-        return os.path.relpath(path, start)
-    except ValueError:  # pragma: no cover
-        return path
+def build_placeholder(
+        num: int,
+        directive: Literal['include', 'include-markdown'],
+) -> str:
+    """Return a placeholder."""
+    directive_prefix = 'im' if directive == 'include-markdown' else 'i'
+    return f'{INLINE_PLACEHOLDER_PREFIX}{directive_prefix}{num}{ETX}'
 
 
-def file_lineno_message(
-        page_src_path: str | None,
-        docs_dir: str,
-        lineno: int,
-) -> str:
-    """Return a message with the file path and line number."""
-    if page_src_path is None:  # pragma: no cover
-        return f'generated page content (line {lineno})'
-    return (
-        f'{safe_os_path_relpath(page_src_path, docs_dir)}'
-        f':{lineno}'
-    )
+@dataclass
+class Settings:  # noqa: D101
+    exclude: list[str] | None
 
 
 def get_file_content(  # noqa: PLR0913, PLR0915
@@ -119,46 +97,55 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         if page_src_path in settings_ignore_paths:
             return markdown
 
+    new_found_include_contents: list[tuple[str, str]] = []
+    new_found_include_markdown_contents: list[tuple[str, str]] = []
+
     def found_include_tag(  # noqa: PLR0912, PLR0915
             match: re.Match[str],
     ) -> str:
         directive_match_start = match.start()
+        directive_lineno = process.lineno_from_content_start(
+            markdown,
+            directive_match_start,
+        )
 
         includer_indent = match['_includer_indent']
 
         filename, raw_filename = parse_filename_argument(match)
         if filename is None:
-            lineno = lineno_from_content_start(
-                markdown,
-                directive_match_start,
+            location = process.file_lineno_message(
+                page_src_path, docs_dir, directive_lineno,
             )
             raise PluginError(
                 "Found no path passed including with 'include'"
-                ' directive at'
-                f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
+                f' directive at {location}',
             )
 
         arguments_string = match['arguments']
 
+        warn_invalid_directive_arguments(
+            arguments_string,
+            directive_lineno,
+            'include',
+            page_src_path,
+            docs_dir,
+        )
+
         exclude_match = ARGUMENT_REGEXES['exclude'].search(arguments_string)
         ignore_paths = [*settings_ignore_paths]
         if exclude_match is not None:
             exclude_string = parse_string_argument(exclude_match)
             if exclude_string is None:
-                lineno = lineno_from_content_start(
-                    markdown,
-                    directive_match_start,
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno,
                 )
                 raise PluginError(
                     "Invalid empty 'exclude' argument in 'include'"
-                    ' directive at'
-                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
+                    f' directive at {location}',
                 )
 
             for path in resolve_file_paths_to_exclude(
-                    exclude_string,
-                    page_src_path,
-                    docs_dir,
+                exclude_string, page_src_path, docs_dir,
             ):
                 if path not in ignore_paths:
                     ignore_paths.append(path)
@@ -171,13 +158,11 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         )
 
         if not file_paths_to_include:
-            lineno = lineno_from_content_start(
-                markdown,
-                directive_match_start,
+            location = process.file_lineno_message(
+                page_src_path, docs_dir, directive_lineno,
             )
             raise PluginError(
-                f"No files found including '{raw_filename}' at"
-                f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
+                f"No files found including '{raw_filename}' at {location}",
             )
 
         if files_watcher is not None and not is_url:
@@ -190,14 +175,12 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             arguments_string,
         )
         if invalid_bool_args:
-            lineno = lineno_from_content_start(
-                markdown,
-                directive_match_start,
+            location = process.file_lineno_message(
+                page_src_path, docs_dir, directive_lineno,
             )
             raise PluginError(
                 f"Invalid value for '{invalid_bool_args[0]}' argument of"
-                " 'include' directive at"
-                f' {file_lineno_message(page_src_path, docs_dir, lineno)}.'
+                f" 'include' directive at {location}."
                 f' Possible values are true or false.',
             )
 
@@ -205,13 +188,12 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         if start_match:
             start = parse_string_argument(start_match)
             if start is None:
-                lineno = lineno_from_content_start(
-                    markdown,
-                    directive_match_start,
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno,
                 )
                 raise PluginError(
                     "Invalid empty 'start' argument in 'include' directive at"
-                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
+                    f' {location}',
                 )
         else:
             start = defaults['start']
@@ -220,13 +202,12 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         if end_match:
             end = parse_string_argument(end_match)
             if end is None:
-                lineno = lineno_from_content_start(
-                    markdown,
-                    directive_match_start,
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno,
                 )
                 raise PluginError(
                     "Invalid empty 'end' argument in 'include' directive at"
-                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
+                    f' {location}',
                 )
         else:
             end = defaults['end']
@@ -235,14 +216,12 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         if encoding_match:
             encoding = parse_string_argument(encoding_match)
             if encoding is None:
-                lineno = lineno_from_content_start(
-                    markdown,
-                    directive_match_start,
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno,
                 )
                 raise PluginError(
                     "Invalid empty 'encoding' argument in 'include'"
-                    ' directive at'
-                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
+                    f' directive at {location}',
                 )
         else:
             encoding = defaults['encoding']
@@ -308,69 +287,72 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             if expected_but_any_found[i]:
                 delimiter_value = locals()[delimiter_name]
                 readable_files_to_include = ', '.join([
-                    safe_os_path_relpath(fpath, docs_dir)
+                    process.safe_os_path_relpath(fpath, docs_dir)
                     for fpath in file_paths_to_include
                 ])
                 plural_suffix = 's' if len(file_paths_to_include) > 1 else ''
-                lineno = lineno_from_content_start(
-                    markdown,
-                    directive_match_start,
-                )
-                file_lineno = file_lineno_message(
-                    page_src_path, docs_dir, lineno,
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno,
                 )
                 logger.warning(
-                    (
-                        f"Delimiter {delimiter_name} '{delimiter_value}'"
-                        " of 'include' directive at"
-                        f' {file_lineno}'
-                        f' not detected in the file{plural_suffix}'
-                        f' {readable_files_to_include}'
-                    ),
+                    f"Delimiter {delimiter_name} '{delimiter_value}'"
+                    f" of 'include' directive at {location}"
+                    f' not detected in the file{plural_suffix}'
+                    f' {readable_files_to_include}',
                 )
 
-        return text_to_include
+        nonlocal new_found_include_contents
+        include_index = len(new_found_include_contents)
+        placeholder = build_placeholder(include_index, 'include')
+        new_found_include_contents.append((placeholder, text_to_include))
+        return placeholder
 
     def found_include_markdown_tag(  # noqa: PLR0912, PLR0915
             match: re.Match[str],
     ) -> str:
         directive_match_start = match.start()
+        directive_lineno = process.lineno_from_content_start(
+            markdown,
+            directive_match_start,
+        )
 
         includer_indent = match['_includer_indent']
         empty_includer_indent = ' ' * len(includer_indent)
 
         filename, raw_filename = parse_filename_argument(match)
         if filename is None:
-            lineno = lineno_from_content_start(
-                markdown,
-                directive_match_start,
+            location = process.file_lineno_message(
+                page_src_path, docs_dir, directive_lineno,
             )
             raise PluginError(
                 "Found no path passed including with 'include-markdown'"
-                f' directive at'
-                f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
+                f' directive at {location}',
             )
 
         arguments_string = match['arguments']
 
+        warn_invalid_directive_arguments(
+            arguments_string,
+            directive_lineno,
+            'include-markdown',
+            page_src_path,
+            docs_dir,
+        )
+
         exclude_match = ARGUMENT_REGEXES['exclude'].search(arguments_string)
         ignore_paths = [*settings_ignore_paths]
         if exclude_match is not None:
             exclude_string = parse_string_argument(exclude_match)
             if exclude_string is None:
-                lineno = lineno_from_content_start(
-                    markdown,
-                    directive_match_start,
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno,
                 )
                 raise PluginError(
                     "Invalid empty 'exclude' argument in 'include-markdown'"
-                    f' directive at'
-                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
+                    f' directive at {location}',
                 )
             for path in resolve_file_paths_to_exclude(
-                    exclude_string,
-                    page_src_path,
-                    docs_dir,
+                exclude_string, page_src_path, docs_dir,
             ):
                 if path not in ignore_paths:
                     ignore_paths.append(path)
@@ -383,13 +365,11 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         )
 
         if not file_paths_to_include:
-            lineno = lineno_from_content_start(
-                markdown,
-                directive_match_start,
+            location = process.file_lineno_message(
+                page_src_path, docs_dir, directive_lineno,
             )
             raise PluginError(
-                f"No files found including '{raw_filename}' at"
-                f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
+                f"No files found including '{raw_filename}' at {location}",
             )
 
         if files_watcher is not None and not is_url:
@@ -399,21 +379,19 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             [
                 'rewrite-relative-urls', 'comments',
                 'preserve-includer-indent', 'dedent',
-                'trailing-newlines',
+                'trailing-newlines', 'recursive',
             ],
             defaults,
             arguments_string,
         )
         if invalid_bool_args:
-            lineno = lineno_from_content_start(
-                markdown,
-                directive_match_start,
+            location = process.file_lineno_message(
+                page_src_path, docs_dir, directive_lineno,
             )
             raise PluginError(
                 f"Invalid value for '{invalid_bool_args[0]}' argument of"
                 " 'include-markdown' directive at"
-                f' {file_lineno_message(page_src_path, docs_dir, lineno)}.'
-                f' Possible values are true or false.',
+                f' {location}. Possible values are true or false.',
             )
 
         # start and end arguments
@@ -421,14 +399,12 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         if start_match:
             start = parse_string_argument(start_match)
             if start is None:
-                lineno = lineno_from_content_start(
-                    markdown,
-                    directive_match_start,
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno,
                 )
                 raise PluginError(
                     "Invalid empty 'start' argument in 'include-markdown'"
-                    f' directive at'
-                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
+                    f' directive at {location}',
                 )
         else:
             start = defaults['start']
@@ -437,14 +413,12 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         if end_match:
             end = parse_string_argument(end_match)
             if end is None:
-                lineno = lineno_from_content_start(
-                    markdown,
-                    directive_match_start,
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno,
                 )
                 raise PluginError(
                     "Invalid empty 'end' argument in 'include-markdown'"
-                    f' directive at'
-                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
+                    f' directive at {location}',
                 )
         else:
             end = defaults['end']
@@ -453,14 +427,12 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         if encoding_match:
             encoding = parse_string_argument(encoding_match)
             if encoding is None:
-                lineno = lineno_from_content_start(
-                    markdown,
-                    directive_match_start,
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno,
                 )
                 raise PluginError(
                     "Invalid empty 'encoding' argument in 'include-markdown'"
-                    ' directive at'
-                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
+                    f' directive at {location}',
                 )
         else:
             encoding = defaults['encoding']
@@ -472,26 +444,22 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         if offset_match:
             offset_raw_value = offset_match[1]
             if offset_raw_value == '':
-                lineno = lineno_from_content_start(
-                    markdown,
-                    directive_match_start,
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno,
                 )
                 raise PluginError(
                     "Invalid empty 'heading-offset' argument in"
-                    " 'include-markdown' directive at"
-                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
+                    f" 'include-markdown' directive at {location}",
                 )
             try:
                 offset = int(offset_raw_value)
             except ValueError:
-                lineno = lineno_from_content_start(
-                    markdown,
-                    directive_match_start,
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno,
                 )
                 raise PluginError(
                     f"Invalid 'heading-offset' argument \"{offset_raw_value}\""
-                    " in 'include-markdown' directive at"
-                    f' {file_lineno_message(page_src_path, docs_dir, lineno)}',
+                    f" in 'include-markdown' directive at {location}",
                 ) from None
         else:
             offset = defaults['heading-offset']
@@ -530,16 +498,17 @@ def get_file_content(  # noqa: PLR0913, 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:
@@ -601,38 +570,45 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             if expected_but_any_found[i]:
                 delimiter_value = locals()[delimiter_name]
                 readable_files_to_include = ', '.join([
-                    safe_os_path_relpath(fpath, docs_dir)
+                    process.safe_os_path_relpath(fpath, docs_dir)
                     for fpath in file_paths_to_include
                 ])
                 plural_suffix = 's' if len(file_paths_to_include) > 1 else ''
-                lineno = lineno_from_content_start(
-                    markdown,
-                    directive_match_start,
-                )
-                file_lineno = file_lineno_message(
-                    page_src_path, docs_dir, lineno,
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno,
                 )
                 logger.warning(
-                    (
-                        f"Delimiter {delimiter_name} '{delimiter_value}' of"
-                        " 'include-markdown' directive at"
-                        f' {file_lineno}'
-                        f' not detected in the file{plural_suffix}'
-                        f' {readable_files_to_include}'
-                    ),
+                    f"Delimiter {delimiter_name} '{delimiter_value}' of"
+                    f" 'include-markdown' directive at {location}"
+                    f' not detected in the file{plural_suffix}'
+                    f' {readable_files_to_include}',
                 )
 
-        return text_to_include
+        nonlocal new_found_include_markdown_contents
+        markdown_include_index = len(new_found_include_markdown_contents)
+        placeholder = build_placeholder(
+            markdown_include_index, 'include-markdown')
+        new_found_include_markdown_contents.append(
+            (placeholder, text_to_include))
+        return placeholder
 
+    # Replace contents by placeholders
     markdown = tags['include-markdown'].sub(
         found_include_markdown_tag,
         markdown,
     )
-    return tags['include'].sub(
+    markdown = tags['include'].sub(
         found_include_tag,
         markdown,
     )
 
+    # Replace placeholders by contents
+    for placeholder, text in new_found_include_contents:
+        markdown = markdown.replace(placeholder, text, 1)
+    for placeholder, text in new_found_include_markdown_contents:
+        markdown = markdown.replace(placeholder, text, 1)
+    return markdown
+
 
 def on_page_markdown(
         markdown: str,

mkdocs_include_markdown_plugin-6.2.0/src/mkdocs_include_markdown_plugin/logger.py

@@ -0,0 +1,10 @@
+"""Mkdocs plugin logger."""
+
+from __future__ import annotations
+
+import logging
+
+
+# TODO: when Mkdocs < 1.5.0 support is dropped, use
+# mkdocs.plugin.get_plugin_logger
+logger = logging.getLogger('mkdocs.plugins.include_markdown')

{mkdocs_include_markdown_plugin-6.1.1 → mkdocs_include_markdown_plugin-6.2.0}/src/mkdocs_include_markdown_plugin/plugin.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from collections.abc import Callable
 from functools import cached_property
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from mkdocs.exceptions import PluginError
 from mkdocs.livereload import LiveReloadServer
@@ -98,7 +98,7 @@ class IncludeMarkdownPlugin(BasePlugin[PluginConfig]):
             self,
             server: LiveReloadServer,
             config: MkDocsConfig,  # noqa: ARG002
-            builder: Callable[[Any], Any],  # noqa: ARG002
+            builder: Callable,  # noqa: ARG002
     ) -> None:
         if self._server is None:  # pragma: no cover
             self._server = server

{mkdocs_include_markdown_plugin-6.1.1 → mkdocs_include_markdown_plugin-6.2.0}/src/mkdocs_include_markdown_plugin/process.py

@@ -13,6 +13,8 @@ from urllib.request import Request, urlopen
 
 
 if TYPE_CHECKING:
+    from typing import Any
+
     from mkdocs_include_markdown_plugin.cache import Cache
 
 
@@ -452,3 +454,38 @@ def read_url(url: str, http_cache: Cache | None) -> Any:
     if http_cache is not None:
         http_cache.set_(url, content)
     return content
+
+
+def safe_os_path_relpath(path: str, start: str) -> str:
+    """Return the relative path of a file from a start directory.
+
+    Safe version of `os.path.relpath` that catches `ValueError` exceptions
+    on Windows and returns the original path in case of error.
+    On Windows, `ValueError` is raised when `path` and `start` are on
+    different drives.
+    """
+    if os.name != 'nt':  # pragma: nt no cover
+        return os.path.relpath(path, start)
+    try:  # pragma: nt cover
+        return os.path.relpath(path, start)
+    except ValueError:  # pragma: no cover
+        return path
+
+
+def file_lineno_message(
+        page_src_path: str | None,
+        docs_dir: str,
+        lineno: int,
+) -> str:
+    """Return a message with the file path and line number."""
+    if page_src_path is None:  # pragma: no cover
+        return f'generated page content (line {lineno})'
+    return (
+        f'{safe_os_path_relpath(page_src_path, docs_dir)}'
+        f':{lineno}'
+    )
+
+
+def lineno_from_content_start(content: str, start: int) -> int:
+    """Return the line number of the first line of ``start`` in ``content``."""
+    return content[:start].count('\n') + 1