mkdocs-include-markdown-plugin 7.1.8__tar.gz → 7.2.1__tar.gz

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.1}/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2017-2025 Joe Rickerby and contributors
+   Copyright 2017-2026 Joe Rickerby and contributors
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-include-markdown-plugin
-Version: 7.1.8
+Version: 7.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
@@ -181,6 +181,8 @@ plugins:
 This plugin provides two directives, one to include Markdown files and another
 to include files of any type.
 
+#### Common arguments
+
 Paths of included files can be either:
 
 - URLs to include remote content.
@@ -199,36 +201,63 @@ single `'` quotes, which can be escaped prepending them a `\` character as
 The arguments **start** and **end** may contain usual (Python-style) escape
 sequences like `\n` to match against newlines.
 
-<!-- mdpo-disable-next-line -->
-
-#### **`include-markdown`**
-
-Includes Markdown files content, optionally using two delimiters to filter the
-content to include.
-
-- <a name="include-markdown_start" href="#include-markdown_start">#</a>
+- <a name="include_start" href="#include_start">#</a>
   **start**: Delimiter that marks the beginning of the content to include.
-- <a name="include-markdown_end" href="#include-markdown_end">#</a>
+- <a name="include_end" href="#include_end">#</a>
   **end**: Delimiter that marks the end of the content to include.
-- <a name="include-markdown_preserve-includer-indent" href="#include-markdown_preserve-includer-indent">#</a>
+- <a name="include_preserve-includer-indent" href="#include_preserve-includer-indent">#</a>
   **preserve-includer-indent** (_true_): When this option is enabled (default),
   every line of the content to include is indented with the same number of
   spaces used to indent the includer `{% %}` template. Possible values are
   `true` and `false`.
-- <a name="include-markdown_dedent" href="#include-markdown_dedent">#</a>
+- <a name="include_dedent" href="#include_dedent">#</a>
   **dedent** (_false_): If enabled, the included content will be dedented.
-- <a name="include-markdown_exclude" href="#include-markdown_exclude">#</a>
+- <a name="include_exclude" href="#include_exclude">#</a>
   **exclude**: Specify with a glob which files should be ignored. Only useful
   when passing globs to include multiple files.
-- <a name="include-markdown_trailing-newlines" href="#include-markdown_trailing-newlines">#</a>
+- <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-markdown_recursive" href="#include-markdown_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-markdown_encoding" href="#include-markdown_encoding">#</a>
+- <a name="include_order" href="#include_order">#</a>
+  **order** (_'alpha-path'_): Define the order in which multiple files are included
+  when using globs. Possible values are:
+  - A combination of an optional order type and an optional order by separated
+    by a hyphen (`-`), and optionally prefixed by a hyphen (`-`) to indicate
+    ascending order. If an order type or an order by is not specified, the defaults
+    are used. It follows the form:
+    `[-]<order_type>-<order_by>` where:
+    - **Order type**:
+      - `'alpha'` (default): Alphabetical order.
+      - `'natural'`: Natural order, so that e.g. `file2.md` comes before `file10.md`.
+    - **Order by**:
+      - `'path'` (default): Order by full file path.
+      - `'name'`: Order by file name only.
+      - `'extension'`: Order by file extension.
+  - A combination of an optional prefix hyphen to denote ascending order and one
+    of the following values in the form `[-]<value>` where `<value>` is one of:
+    - `'size'`: Order by file size.
+    - `'mtime'`: Order by file modification time.
+    - `'ctime'`: Order by file creation time (or the last metadata change time
+      on Unix systems).
+    - `'atime'`: Order by file last access time.
+    - `'system'`: Order provided by the operating system. This is the same as not
+      specifying any order and relying on the default order of the filesystem.
+      This may be different between operating systems, so use it with care.
+  - `'random'`: Random order.
+- <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.
+
+<!-- mdpo-disable-next-line -->
+
+#### **`include-markdown`**
+
+Includes Markdown files content, optionally using two delimiters to filter the
+content to include.
+
 - <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
@@ -284,6 +313,7 @@ content to include.
 {%
     include-markdown "**"
     exclude="./{index,LICENSE}.md"
+    order="name"
 %}
 ```
 
@@ -291,36 +321,19 @@ content to include.
 {% include-markdown '/escap\'ed/single-quotes/in/file\'/name.md' %}
 ```
 
+```jinja
+{%
+    include-markdown "**"
+    order="-natural-extension"
+%}
+```
+
 <!-- mdpo-disable-next-line -->
 
 #### **`include`**
 
 Includes the content of a file or a group of files.
 
-- <a name="include_start" href="#include_start">#</a>
-  **start**: Delimiter that marks the beginning of the content to include.
-- <a name="include_end" href="#include_end">#</a>
-  **end**: Delimiter that marks the end of the content to include.
-- <a name="include_preserve-includer-indent" href="#include_preserve-includer-indent">#</a>
-  **preserve-includer-indent** (_true_): When this option is enabled (default),
-  every line of the content to include is indented with the same number of
-  spaces used to indent the includer `{% %}` template. Possible values are
-  `true` and `false`.
-- <a name="include_dedent" href="#include_dedent">#</a>
-  **dedent** (_false_): If enabled, the included content will be dedented.
-- <a name="include_exclude" href="#include_exclude">#</a>
-  **exclude**: Specify with a glob which files should be ignored. Only useful
-  when passing globs to include multiple 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.
-
 ##### Examples
 
 ```jinja
@@ -341,6 +354,7 @@ Includes the content of a file or a group of files.
 {%
     include '**'
     exclude='./*.md'
+    order='random'
 %}
 ```
 

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.1}/README.md

@@ -146,6 +146,8 @@ plugins:
 This plugin provides two directives, one to include Markdown files and another
 to include files of any type.
 
+#### Common arguments
+
 Paths of included files can be either:
 
 - URLs to include remote content.
@@ -164,36 +166,63 @@ single `'` quotes, which can be escaped prepending them a `\` character as
 The arguments **start** and **end** may contain usual (Python-style) escape
 sequences like `\n` to match against newlines.
 
-<!-- mdpo-disable-next-line -->
-
-#### **`include-markdown`**
-
-Includes Markdown files content, optionally using two delimiters to filter the
-content to include.
-
-- <a name="include-markdown_start" href="#include-markdown_start">#</a>
+- <a name="include_start" href="#include_start">#</a>
   **start**: Delimiter that marks the beginning of the content to include.
-- <a name="include-markdown_end" href="#include-markdown_end">#</a>
+- <a name="include_end" href="#include_end">#</a>
   **end**: Delimiter that marks the end of the content to include.
-- <a name="include-markdown_preserve-includer-indent" href="#include-markdown_preserve-includer-indent">#</a>
+- <a name="include_preserve-includer-indent" href="#include_preserve-includer-indent">#</a>
   **preserve-includer-indent** (_true_): When this option is enabled (default),
   every line of the content to include is indented with the same number of
   spaces used to indent the includer `{% %}` template. Possible values are
   `true` and `false`.
-- <a name="include-markdown_dedent" href="#include-markdown_dedent">#</a>
+- <a name="include_dedent" href="#include_dedent">#</a>
   **dedent** (_false_): If enabled, the included content will be dedented.
-- <a name="include-markdown_exclude" href="#include-markdown_exclude">#</a>
+- <a name="include_exclude" href="#include_exclude">#</a>
   **exclude**: Specify with a glob which files should be ignored. Only useful
   when passing globs to include multiple files.
-- <a name="include-markdown_trailing-newlines" href="#include-markdown_trailing-newlines">#</a>
+- <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-markdown_recursive" href="#include-markdown_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-markdown_encoding" href="#include-markdown_encoding">#</a>
+- <a name="include_order" href="#include_order">#</a>
+  **order** (_'alpha-path'_): Define the order in which multiple files are included
+  when using globs. Possible values are:
+  - A combination of an optional order type and an optional order by separated
+    by a hyphen (`-`), and optionally prefixed by a hyphen (`-`) to indicate
+    ascending order. If an order type or an order by is not specified, the defaults
+    are used. It follows the form:
+    `[-]<order_type>-<order_by>` where:
+    - **Order type**:
+      - `'alpha'` (default): Alphabetical order.
+      - `'natural'`: Natural order, so that e.g. `file2.md` comes before `file10.md`.
+    - **Order by**:
+      - `'path'` (default): Order by full file path.
+      - `'name'`: Order by file name only.
+      - `'extension'`: Order by file extension.
+  - A combination of an optional prefix hyphen to denote ascending order and one
+    of the following values in the form `[-]<value>` where `<value>` is one of:
+    - `'size'`: Order by file size.
+    - `'mtime'`: Order by file modification time.
+    - `'ctime'`: Order by file creation time (or the last metadata change time
+      on Unix systems).
+    - `'atime'`: Order by file last access time.
+    - `'system'`: Order provided by the operating system. This is the same as not
+      specifying any order and relying on the default order of the filesystem.
+      This may be different between operating systems, so use it with care.
+  - `'random'`: Random order.
+- <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.
+
+<!-- mdpo-disable-next-line -->
+
+#### **`include-markdown`**
+
+Includes Markdown files content, optionally using two delimiters to filter the
+content to include.
+
 - <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
@@ -249,6 +278,7 @@ content to include.
 {%
     include-markdown "**"
     exclude="./{index,LICENSE}.md"
+    order="name"
 %}
 ```
 
@@ -256,36 +286,19 @@ content to include.
 {% include-markdown '/escap\'ed/single-quotes/in/file\'/name.md' %}
 ```
 
+```jinja
+{%
+    include-markdown "**"
+    order="-natural-extension"
+%}
+```
+
 <!-- mdpo-disable-next-line -->
 
 #### **`include`**
 
 Includes the content of a file or a group of files.
 
-- <a name="include_start" href="#include_start">#</a>
-  **start**: Delimiter that marks the beginning of the content to include.
-- <a name="include_end" href="#include_end">#</a>
-  **end**: Delimiter that marks the end of the content to include.
-- <a name="include_preserve-includer-indent" href="#include_preserve-includer-indent">#</a>
-  **preserve-includer-indent** (_true_): When this option is enabled (default),
-  every line of the content to include is indented with the same number of
-  spaces used to indent the includer `{% %}` template. Possible values are
-  `true` and `false`.
-- <a name="include_dedent" href="#include_dedent">#</a>
-  **dedent** (_false_): If enabled, the included content will be dedented.
-- <a name="include_exclude" href="#include_exclude">#</a>
-  **exclude**: Specify with a glob which files should be ignored. Only useful
-  when passing globs to include multiple 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.
-
 ##### Examples
 
 ```jinja
@@ -306,6 +319,7 @@ Includes the content of a file or a group of files.
 {%
     include '**'
     exclude='./*.md'
+    order='random'
 %}
 ```
 

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs-include-markdown-plugin"
-version = "7.1.8"
+version = "7.2.1"
 description = "Mkdocs Markdown includer plugin."
 readme = "README.md"
 license = "Apache-2.0"
@@ -151,7 +151,7 @@ select = [
   "COM",
   "SLOT",
 ]
-ignore = ["G004"]
+ignore = ["G004", "E731"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.1}/src/mkdocs_include_markdown_plugin/config.py

@@ -20,6 +20,7 @@ class PluginConfig(Config):  # noqa: D101
     comments = MkType(bool, default=False)
     rewrite_relative_urls = MkType(bool, default=True)
     heading_offset = MkType(int, default=0)
+    order = MkType(str, default='alpha-path')
     start = Optional(MkType(str))
     end = Optional(MkType(str))
     exclude = ListOfItems(MkType(str), default=[])

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.1}/src/mkdocs_include_markdown_plugin/directive.py

@@ -13,8 +13,15 @@ from typing import TYPE_CHECKING
 from mkdocs.exceptions import PluginError
 from wcmatch import glob
 
-from mkdocs_include_markdown_plugin import process
 from mkdocs_include_markdown_plugin.logger import logger
+from mkdocs_include_markdown_plugin.process import (
+    file_lineno_message,
+    filter_paths,
+    is_absolute_path,
+    is_relative_path,
+    is_url,
+    sort_paths,
+)
 
 
 @dataclass
@@ -28,6 +35,7 @@ if TYPE_CHECKING:  # pragma: no cover
     from typing import Callable, Literal, TypedDict
 
     DirectiveBoolArgumentsDict = dict[str, DirectiveBoolArgument]
+    OrderOption = tuple[bool, str, str]
 
     DefaultValues = TypedDict(
         'DefaultValues', {
@@ -41,6 +49,7 @@ if TYPE_CHECKING:  # pragma: no cover
             'recursive': bool,
             'start': str | None,
             'end': str | None,
+            'order': str,
         },
     )
 
@@ -92,10 +101,12 @@ def str_arg(arg: str) -> re.Pattern[str]:
 
 
 ARGUMENT_REGEXES = {
+    # str
     'start': functools.partial(str_arg, 'start'),
     'end': functools.partial(str_arg, 'end'),
     'exclude': functools.partial(str_arg, 'exclude'),
     'encoding': functools.partial(str_arg, 'encoding'),
+    'order': functools.partial(str_arg, 'order'),
 
     # bool
     'comments': functools.partial(arg, 'comments'),
@@ -129,7 +140,7 @@ def _maybe_arguments_iter(arguments_string: str) -> Iterable[str]:
     inside_string = False
     escaping = False
     opening_argument = False  # whether we are at the beginning of an argument
-    current_value = ''
+    current_value: list[str] = []
 
     for c in arguments_string:
         if inside_string:
@@ -142,24 +153,25 @@ def _maybe_arguments_iter(arguments_string: str) -> Iterable[str]:
             else:
                 escaping = False
         elif c == '=':
+            current_value_str = ''.join(current_value)
             new_current_value = ''
-            for ch in reversed(current_value):
+            for ch in reversed(current_value_str):
                 if ch in string.whitespace:
-                    current_value = new_current_value[::-1]
+                    current_value_str = new_current_value[::-1]
                     break
                 new_current_value += ch
-            yield current_value
-            current_value = ''
+            yield current_value_str
+            current_value = []
             opening_argument = True
         elif opening_argument:
             opening_argument = False
             if c in ('"', "'"):
                 current_string_opening = c
                 inside_string = True
-                current_value += c
-                current_value += c
+                current_value.append(c)
+                current_value.append(c)
         else:
-            current_value += c
+            current_value.append(c)
 
 
 def warn_invalid_directive_arguments(
@@ -178,7 +190,7 @@ def warn_invalid_directive_arguments(
     )
     for maybe_arg in _maybe_arguments_iter(arguments_string):
         if maybe_arg not in valid_args:
-            location = process.file_lineno_message(
+            location = file_lineno_message(
                 page_src_path, docs_dir, directive_lineno(),
             )
             logger.warning(
@@ -283,12 +295,13 @@ def resolve_file_paths_to_include(  # noqa: PLR0912
     includer_page_src_path: str | None,
     docs_dir: str,
     ignore_paths: list[str],
+    order: str,
 ) -> tuple[list[str], bool]:
     """Resolve the file paths to include for a directive."""
-    if process.is_url(include_string):
+    if is_url(include_string):
         return [include_string], True
 
-    if process.is_absolute_path(include_string):
+    if is_absolute_path(include_string):
         if os.name == 'nt':  # pragma: no cover
             # Windows
             fpath = os.path.normpath(include_string)
@@ -299,21 +312,25 @@ def resolve_file_paths_to_include(  # noqa: PLR0912
             if not is_file:
                 return [], False
 
-            return process.filter_paths(
-                [fpath], ignore_paths,
-            ), False
+            paths = filter_paths([fpath], ignore_paths)
+            is_url_ = False
+            return sort_paths(paths, parse_order_option(order)), is_url_
 
         try:
             is_file = stat.S_ISREG(os.stat(include_string).st_mode)
         except (FileNotFoundError, OSError):
             is_file = False
-        return process.filter_paths(
+        paths = filter_paths(
             [include_string] if is_file else glob.iglob(
                 include_string, flags=GLOB_FLAGS,
             ),
-            ignore_paths), False
+            ignore_paths,
+        )
+        is_url_ = False
+        sort_paths(paths, parse_order_option(order))
+        return paths, is_url_
 
-    if process.is_relative_path(include_string):
+    if is_relative_path(include_string):
         if includer_page_src_path is None:  # pragma: no cover
             raise PluginError(
                 'Relative paths are not allowed when the includer page'
@@ -338,7 +355,10 @@ def resolve_file_paths_to_include(  # noqa: PLR0912
                 root_dir=root_dir,
             ):
                 paths.append(os.path.join(root_dir, fp))
-        return process.filter_paths(paths, ignore_paths), False
+        paths = filter_paths(paths, ignore_paths)
+        is_url_ = False
+        sort_paths(paths, parse_order_option(order))
+        return paths, is_url_
 
     # relative to docs_dir
     paths = []
@@ -357,7 +377,10 @@ def resolve_file_paths_to_include(  # noqa: PLR0912
             root_dir=root_dir,
         ):
             paths.append(os.path.join(root_dir, fp))
-    return process.filter_paths(paths, ignore_paths), False
+    paths = filter_paths(paths, ignore_paths)
+    is_url_ = False
+    sort_paths(paths, parse_order_option(order))
+    return paths, is_url_
 
 
 def resolve_file_paths_to_exclude(
@@ -366,10 +389,10 @@ def resolve_file_paths_to_exclude(
     docs_dir: str,
 ) -> list[str]:
     """Resolve the file paths to exclude for a directive."""
-    if process.is_absolute_path(exclude_string):
+    if is_absolute_path(exclude_string):
         return glob.glob(exclude_string, flags=GLOB_FLAGS)
 
-    if process.is_relative_path(exclude_string):
+    if is_relative_path(exclude_string):
         if includer_page_src_path is None:  # pragma: no cover
             raise PluginError(
                 'Relative paths are not allowed when the includer page'
@@ -394,3 +417,58 @@ def resolve_file_paths_to_exclude(
         flags=GLOB_FLAGS,
         root_dir=docs_dir,
     )
+
+
+def validate_order_option(
+        order: str,
+        page_src_path: str | None,
+        docs_dir: str,
+        directive_lineno: Callable[[], int],
+        directive: str,
+) -> None:
+    """Validate the 'order' option."""
+    regex = get_order_option_regex()
+    match = regex.match(order)
+    if not match:
+        location = file_lineno_message(
+            page_src_path, docs_dir, directive_lineno(),
+        )
+        raise PluginError(
+            f"Invalid value '{order}' for the 'order' argument in"
+            f" '{directive}' directive at {location}. The argument"
+            " 'order' must be a string that matches the regex"
+            f" '{regex.pattern}'.",
+        )
+
+
+@functools.cache
+def get_order_option_regex() -> re.Pattern[str]:
+    """Return the compiled regex to validate the 'order' option."""
+    return re.compile(
+        r'^-?'
+        r'(?:'
+        r'(?:alpha|natural)?(?:-?(?:path|name|extension))?'
+        r'|system|random|size|mtime|ctime|atime'
+        r')?$',
+    )
+
+
+def parse_order_option(order: str) -> OrderOption:
+    """Parse the 'order' option into a tuple."""
+    ascending = False
+    order_type = 'alpha'
+    order_by = 'path'
+    if order.startswith('-'):
+        ascending = True
+        order = order[1:]
+    order_split = order.split('-', 1)
+    if len(order_split) == 2:  # noqa: PLR2004
+        order_type, order_by = order_split
+    elif order_split[0] in (
+        'alpha', 'random', 'natural', 'system',
+        'size', 'mtime', 'ctime', 'atime',
+    ):
+        order_type = order_split[0]
+    elif order_split[0] in ('name', 'path', 'extension'):
+        order_by = order_split[0]
+    return ascending, order_type, order_by

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.1}/src/mkdocs_include_markdown_plugin/event.py

@@ -24,6 +24,7 @@ from mkdocs_include_markdown_plugin.directive import (
     parse_string_argument,
     resolve_file_paths_to_exclude,
     resolve_file_paths_to_include,
+    validate_order_option,
     warn_invalid_directive_arguments,
 )
 from mkdocs_include_markdown_plugin.files_watcher import FilesWatcher
@@ -141,13 +142,42 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             ):
                 ignore_paths.append(path)
 
+        order = defaults['order']
+        if 'order' in used_arguments:
+            order_match = ARGUMENT_REGEXES['order']().search(
+                arguments_string,
+            )
+            order_ = parse_string_argument(order_match)
+            if order_ is None:
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno(),
+                )
+                raise PluginError(
+                    "Invalid empty 'order' argument in 'include'"
+                    f' directive at {location}',
+                )
+            validate_order_option(
+                order_, page_src_path, docs_dir, directive_lineno, 'include',
+            )
+            order = order_
+
         file_paths_to_include, is_url = resolve_file_paths_to_include(
             filename,
             page_src_path,
             docs_dir,
             ignore_paths,
+            order,
         )
 
+        if is_url and 'order' in used_arguments:  # pragma: no cover
+            location = process.file_lineno_message(
+                page_src_path, docs_dir, directive_lineno(),
+            )
+            logger.warning(
+                f"Ignoring 'order' argument of 'include' directive"
+                f" at {location} because the included path is a URL",
+            )
+
         if not file_paths_to_include:
             location = process.file_lineno_message(
                 page_src_path, docs_dir, directive_lineno(),
@@ -353,13 +383,46 @@ def get_file_content(  # noqa: PLR0913, PLR0915
             ):
                 ignore_paths.append(path)
 
+        order = defaults['order']
+        if 'order' in used_arguments:
+            order_match = ARGUMENT_REGEXES['order']().search(
+                arguments_string,
+            )
+            order_ = parse_string_argument(order_match)
+            if order_ is None:
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno(),
+                )
+                raise PluginError(
+                    "Invalid empty 'order' argument in 'include-markdown'"
+                    f' directive at {location}',
+                )
+            validate_order_option(
+                order_,
+                page_src_path,
+                docs_dir,
+                directive_lineno,
+                'include-markdown',
+            )
+            order = order_
+
         file_paths_to_include, is_url = resolve_file_paths_to_include(
             filename,
             page_src_path,
             docs_dir,
             ignore_paths,
+            order,
         )
 
+        if is_url and 'order' in used_arguments:  # pragma: no cover
+            location = process.file_lineno_message(
+                page_src_path, docs_dir, directive_lineno(),
+            )
+            logger.warning(
+                f"Ignoring 'order' argument of 'include-markdown' directive"
+                f" at {location} because the included path is a URL",
+            )
+
         if not file_paths_to_include:
             location = process.file_lineno_message(
                 page_src_path, docs_dir, directive_lineno(),
@@ -482,7 +545,7 @@ def get_file_content(  # noqa: PLR0913, PLR0915
         # but they have been specified, so the warning(s) must be raised
         expected_but_any_found = [start is not None, end is not None]
 
-        text_to_include = ''
+        text_to_include_parts = []
         for file_path in file_paths_to_include:
             if process.is_url(filename):
                 new_text_to_include = process.read_url(
@@ -558,11 +621,10 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                 new_text_to_include
             ):
                 lines = new_text_to_include.splitlines(keepends=True)
-                new_text_to_include = lines[0]
+                indented_lines = [lines[0]]
                 for i in range(1, len(lines)):
-                    new_text_to_include += (
-                        filled_includer_indent + lines[i]
-                    )
+                    indented_lines.append(filled_includer_indent + lines[i])
+                new_text_to_include = ''.join(indented_lines)
 
             if offset:
                 new_text_to_include = process.increase_headings_offset(
@@ -570,7 +632,9 @@ def get_file_content(  # noqa: PLR0913, PLR0915
                     offset=offset + cumulative_heading_offset,
                 )
 
-            text_to_include += new_text_to_include
+            text_to_include_parts.append(new_text_to_include)
+
+        text_to_include = ''.join(text_to_include_parts)
 
         # warn if expected start or ends haven't been found in included content
         for i, delimiter_name in enumerate(['start', 'end']):
@@ -645,6 +709,7 @@ def on_page_markdown(
             'recursive': config.recursive,
             'start': config.start,
             'end': config.end,
+            'order': config.order,
         },
         Settings(
             exclude=config.exclude,

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.1}/src/mkdocs_include_markdown_plugin/plugin.py

@@ -11,7 +11,6 @@ from mkdocs.plugins import BasePlugin, event_priority
 
 
 if TYPE_CHECKING:  # pragma: no cover
-
     from mkdocs.config.defaults import MkDocsConfig
     from mkdocs.livereload import LiveReloadServer
     from mkdocs.structure.files import Files
@@ -19,6 +18,9 @@ if TYPE_CHECKING:  # pragma: no cover
 
 from mkdocs_include_markdown_plugin.cache import Cache, initialize_cache
 from mkdocs_include_markdown_plugin.config import PluginConfig
+from mkdocs_include_markdown_plugin.directive import (
+    get_order_option_regex,
+)
 from mkdocs_include_markdown_plugin.event import (
     on_page_markdown as _on_page_markdown,
 )
@@ -50,6 +52,15 @@ class IncludeMarkdownPlugin(BasePlugin[PluginConfig]):
                         ' "include-markdown".',
                     )
 
+        if self.config.order != 'alpha-path':
+            regex = get_order_option_regex()
+            if not regex.match(self.config.order):
+                raise PluginError(
+                    f"Invalid value '{self.config.order}' for the 'order'"
+                    ' global setting. Order must be a string'
+                    f" that matches the regex '{regex.pattern}'.",
+                )
+
         return config
 
     @cached_property

{mkdocs_include_markdown_plugin-7.1.8 → mkdocs_include_markdown_plugin-7.2.1}/src/mkdocs_include_markdown_plugin/process.py

@@ -15,6 +15,7 @@ if TYPE_CHECKING:  # pragma: no cover
     from typing import Any
 
     from mkdocs_include_markdown_plugin.cache import Cache
+    from mkdocs_include_markdown_plugin.directive import OrderOption
 
 
 # Markdown regular expressions. Taken from the original Markdown.pl by John
@@ -173,10 +174,12 @@ def transform_p_by_p_skipping_codeblocks(  # noqa: PLR0912, PLR0915
     _maybe_icodeblock_lines: list[str] = []
     _previous_line_was_empty = False
 
-    lines, current_paragraph = ([], '')
+    lines = []
+    current_paragraph_lines: list[str] = []
 
     def process_current_paragraph() -> None:
-        lines.extend(func(current_paragraph).splitlines(keepends=True))
+        lines.extend(func(''.join(current_paragraph_lines),
+                          ).splitlines(keepends=True))
 
     # The next implementation takes into account that indented code
     # blocks must be surrounded by newlines as per the CommonMark
@@ -190,25 +193,24 @@ def transform_p_by_p_skipping_codeblocks(  # noqa: PLR0912, PLR0915
             if lstripped_line.startswith(('```', '~~~')):
                 _current_fcodeblock_delimiter = lstripped_line[:3]
                 process_current_paragraph()
-                current_paragraph = ''
+                current_paragraph_lines = []
                 lines.append(line)
             elif line.startswith('    '):
                 if not lstripped_line or _maybe_icodeblock_lines:
                     # maybe enter indented codeblock
                     _maybe_icodeblock_lines.append(line)
                 else:
-                    current_paragraph += line
+                    current_paragraph_lines.append(line)
             elif _maybe_icodeblock_lines:
                 process_current_paragraph()
-                current_paragraph = ''
+                current_paragraph_lines = []
                 if not _previous_line_was_empty:
                     # wasn't an indented code block
-                    for line_ in _maybe_icodeblock_lines:
-                        current_paragraph += line_
+                    current_paragraph_lines.extend(_maybe_icodeblock_lines)
                     _maybe_icodeblock_lines = []
-                    current_paragraph += line
+                    current_paragraph_lines.append(line)
                     process_current_paragraph()
-                    current_paragraph = ''
+                    current_paragraph_lines = []
                 else:
                     # exit indented codeblock
                     for line_ in _maybe_icodeblock_lines:
@@ -216,7 +218,7 @@ def transform_p_by_p_skipping_codeblocks(  # noqa: PLR0912, PLR0915
                     _maybe_icodeblock_lines = []
                     lines.append(line)
             else:
-                current_paragraph += line
+                current_paragraph_lines.append(line)
             _previous_line_was_empty = not lstripped_line
         else:
             lines.append(line)
@@ -229,14 +231,13 @@ def transform_p_by_p_skipping_codeblocks(  # noqa: PLR0912, PLR0915
         if not _previous_line_was_empty:
             # at EOF
             process_current_paragraph()
-            current_paragraph = ''
-            for line_ in _maybe_icodeblock_lines:
-                current_paragraph += line_
+            current_paragraph_lines = []
+            current_paragraph_lines.extend(_maybe_icodeblock_lines)
             process_current_paragraph()
-            current_paragraph = ''
+            current_paragraph_lines = []
         else:
             process_current_paragraph()
-            current_paragraph = ''
+            current_paragraph_lines = []
             for line_ in _maybe_icodeblock_lines:
                 lines.append(line_)
     else:
@@ -494,12 +495,12 @@ def filter_paths(
 
     Args:
         filepaths (list): Set of source paths to filter.
-        ignore_paths (list): Paths that must not be included in the response.
+        ignore_paths (list): Paths that are ignored.
 
     Returns:
         list: Non filtered paths ordered alphabetically.
     """
-    response = []
+    result = []
     for filepath in filepaths:
         # ignore by filepath
         if filepath in ignore_paths:
@@ -514,11 +515,60 @@ def filter_paths(
         # ignore if is a directory
         try:
             if not stat.S_ISDIR(os.stat(filepath).st_mode):
-                response.append(filepath)
+                result.append(filepath)
         except (FileNotFoundError, OSError):  # pragma: no cover
             continue
-    response.sort()
-    return response
+    return result
+
+
+def natural_sort_key(s: str) -> list[Any]:
+    """Key function for natural sorting of strings."""
+    return [int(text) if text.isdigit() else text.lower()
+            for text in re.split(r'(\d+)', s)]
+
+
+def sort_paths(paths: list[str], order: OrderOption) -> list[str]:
+    """Sort a list of paths in-place according to an order option."""
+    ascending, order_type, order_by = order
+
+    if order_type == 'random':
+        import random  # noqa: PLC0415
+
+        random.shuffle(paths)
+        return paths
+
+    key = None
+    if order_type == 'alpha':
+        if order_by == 'name':
+            def key(p: str) -> str:
+                return os.path.basename(p)
+        elif order_by == 'extension':
+            def key(p: str) -> str:
+                return os.path.splitext(p)[1]
+    elif order_type == 'natural':
+        if order_by == 'extension':
+            def key(p: str) -> str:
+                return natural_sort_key(os.path.splitext(p)[1])  # type: ignore
+        elif order_by == 'name':
+            def key(p: str) -> str:
+                return natural_sort_key(os.path.basename(p))  # type: ignore
+        else:
+            key = natural_sort_key  # type: ignore
+    elif order_type == 'size':
+        def key(p: str) -> int:  # type: ignore
+            return os.path.getsize(p)
+        ascending = not ascending  # larger files first
+    elif order_type == 'mtime':
+        def key(p: str) -> float:  # type: ignore
+            return os.path.getmtime(p)
+    elif order_type == 'ctime':
+        def key(p: str) -> float:  # type: ignore
+            return os.path.getctime(p)
+    elif order_type == 'atime':
+        def key(p: str) -> float:  # type: ignore
+            return os.path.getatime(p)
+    paths.sort(key=key, reverse=ascending)
+    return paths
 
 
 def _is_valid_url_scheme_char(c: str) -> bool: