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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: mkdocs-include-markdown-plugin
-Version: 6.1.1
+Version: 6.2.1
 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
@@ -43,6 +43,7 @@ Description-Content-Type: text/markdown
 [![License][license-image]][license-link]
 [![Tests][tests-image]][tests-link]
 [![Coverage status][coverage-image]][coverage-link]
+[![Downloads][downloads-image]][downloads-link]
 
 <!-- mdpo-enable -->
 
@@ -190,9 +191,12 @@ 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.
+  **encoding** (_'utf-8'_): Specify the encoding of the included file.
+  If not defined `'utf-8'` will be used.
 - <a name="include-markdown_rewrite-relative-urls" href="#include-markdown_rewrite-relative-urls">#</a>
   **rewrite-relative-urls** (_true_): When this option is enabled (default),
   Markdown links and images in the content that are specified by a relative URL
@@ -212,42 +216,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 +282,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_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>
+- <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.
 
 ##### Examples
 
@@ -295,23 +299,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
@@ -326,9 +331,14 @@ Includes the content of a file or a group of files.
 [coverage-link]: https://app.codecov.io/gh/mondeja/mkdocs-include-markdown-plugin
 [license-image]: https://img.shields.io/pypi/l/mkdocs-include-markdown-plugin?color=light-green&logo=apache&logoColor=white
 [license-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/LICENSE
+[downloads-image]: https://img.shields.io/pypi/dm/mkdocs-include-markdown-plugin
+[downloads-link]: https://pepy.tech/project/mkdocs-include-markdown-plugin
 [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.1}/README.md

@@ -8,6 +8,7 @@
 [![License][license-image]][license-link]
 [![Tests][tests-image]][tests-link]
 [![Coverage status][coverage-image]][coverage-link]
+[![Downloads][downloads-image]][downloads-link]
 
 <!-- mdpo-enable -->
 
@@ -155,9 +156,12 @@ 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.
+  **encoding** (_'utf-8'_): Specify the encoding of the included file.
+  If not defined `'utf-8'` will be used.
 - <a name="include-markdown_rewrite-relative-urls" href="#include-markdown_rewrite-relative-urls">#</a>
   **rewrite-relative-urls** (_true_): When this option is enabled (default),
   Markdown links and images in the content that are specified by a relative URL
@@ -177,42 +181,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 +247,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_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>
+- <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.
 
 ##### Examples
 
@@ -260,23 +264,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
@@ -291,9 +296,14 @@ Includes the content of a file or a group of files.
 [coverage-link]: https://app.codecov.io/gh/mondeja/mkdocs-include-markdown-plugin
 [license-image]: https://img.shields.io/pypi/l/mkdocs-include-markdown-plugin?color=light-green&logo=apache&logoColor=white
 [license-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/LICENSE
+[downloads-image]: https://img.shields.io/pypi/dm/mkdocs-include-markdown-plugin
+[downloads-link]: https://pepy.tech/project/mkdocs-include-markdown-plugin
 [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.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs-include-markdown-plugin"
-version = "6.1.1"
+version = "6.2.1"
 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.1}/src/mkdocs_include_markdown_plugin/cache.py

@@ -39,24 +39,24 @@ class Cache:
             hashlib.sha3_512(url.encode()).digest(),
         ).decode('utf-8')
 
-    def read_file(self, fpath: str) -> str:  # noqa: D102
-        with open(fpath, encoding='utf-8') as f:
+    def read_file(self, fpath: str, encoding: str = 'utf-8') -> str:  # noqa: D102
+        with open(fpath, encoding=encoding) as f:
             return f.read().split('\n', 1)[1]
 
-    def get_(self, url: str) -> str | None:  # noqa: D102
+    def get_(self, url: str, encoding: str = 'utf-8') -> str | None:  # noqa: D102
         key = self.generate_unique_key_from_url(url)
         fpath = os.path.join(self.cache_dir, key)
         if os.path.isfile(fpath):
             creation_time = self.get_creation_time_from_fpath(fpath)
             if time.time() < creation_time + self.expiration_seconds:
-                return self.read_file(fpath)
+                return self.read_file(fpath, encoding=encoding)
             os.remove(fpath)
         return None
 
-    def set_(self, url: str, value: str) -> None:  # noqa: D102
+    def set_(self, url: str, value: str, encoding: str = 'utf-8') -> None:  # noqa: D102
         key = self.generate_unique_key_from_url(url)
         fpath = os.path.join(self.cache_dir, key)
-        with open(fpath, 'w', encoding='utf-8') as f:
+        with open(fpath, 'w', encoding=encoding) as f:
             f.write(f'{int(time.time())}\n')
             f.write(value)
 

{mkdocs_include_markdown_plugin-6.1.1 → mkdocs_include_markdown_plugin-6.2.1}/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,14 +45,14 @@ 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
 # closing tags in the `on_config` plugin event.
 INCLUDE_TAG_RE = rf'''
-    (?P<_includer_indent>[ \t\f\v\w{re.escape(string.punctuation)}]*?)$OPENING_TAG
+    (?P<_includer_indent>[ \t\w\\.]*?)$OPENING_TAG
     \s*
     include
     \s+
@@ -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],
@@ -138,7 +171,7 @@ def create_include_tag(
     """Create a regex pattern to match an inclusion tag directive.
 
     Replaces the substrings '$OPENING_TAG' and '$CLOSING_TAG' from
-    INCLUDE_TAG_REGEX by the effective tag.
+    INCLUDE_TAG_RE by the effective tag.
     """
     return re.compile(
         INCLUDE_TAG_RE.replace(' include', f' {tag}').replace(

{mkdocs_include_markdown_plugin-6.1.1 → mkdocs_include_markdown_plugin-6.2.1}/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')
-
-
-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
+# 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 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']
@@ -251,7 +230,9 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         expected_but_any_found = [start is not None, end is not None]
         for file_path in file_paths_to_include:
             if process.is_url(filename):
-                new_text_to_include = process.read_url(file_path, http_cache)
+                new_text_to_include = process.read_url(
+                    file_path, http_cache, encoding,
+                )
             else:
                 new_text_to_include = process.read_file(file_path, encoding)
 
@@ -308,69 +289,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 +367,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 +381,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 +401,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 +415,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 +429,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 +446,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']
@@ -513,7 +483,9 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         text_to_include = ''
         for file_path in file_paths_to_include:
             if process.is_url(filename):
-                new_text_to_include = process.read_url(file_path, http_cache)
+                new_text_to_include = process.read_url(
+                    file_path, http_cache, encoding,
+                )
             else:
                 new_text_to_include = process.read_file(file_path, encoding)
 
@@ -530,16 +502,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 +574,47 @@ 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.1/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.1}/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.1}/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
 
 
@@ -441,14 +443,53 @@ def read_file(file_path: str, encoding: str) -> str:
         return f.read()
 
 
-def read_url(url: str, http_cache: Cache | None) -> Any:
+def read_url(
+        url: str,
+        http_cache: Cache | None,
+        encoding: str = 'utf-8',
+) -> Any:
     """Read an HTTP location and return its content."""
     if http_cache is not None:
-        cached_content = http_cache.get_(url)
+        cached_content = http_cache.get_(url, encoding)
         if cached_content is not None:
             return cached_content
     with urlopen(Request(url)) as response:
-        content = response.read().decode('UTF-8')
+        content = response.read().decode(encoding)
     if http_cache is not None:
-        http_cache.set_(url, content)
+        http_cache.set_(url, content, encoding)
     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