Fix natural order by extension not correctly applied

Author: mondeja

pyproject.toml

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

src/mkdocs_include_markdown_plugin/process.py

@@ -547,8 +547,11 @@ 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
+            def key(p: str) -> tuple:  # type: ignore
+                return (
+                    natural_sort_key(os.path.splitext(p)[1]),
+                    natural_sort_key(os.path.basename(p)),
+                )
         elif order_by == 'name':
             def key(p: str) -> str:
                 return natural_sort_key(os.path.basename(p))  # type: ignore

tests/test_unit/test_order.py

@@ -6,6 +6,7 @@
 
 from mkdocs_include_markdown_plugin.directive import get_order_option_regex
 from mkdocs_include_markdown_plugin.event import on_page_markdown
+from mkdocs_include_markdown_plugin.process import sort_paths
 from testing_helpers import parametrize_directives, unix_only, windows_only
 
 
@@ -387,6 +388,29 @@ def test_natural_order_by_extension(directive, page, tmp_path, plugin):
     ) == 'file1.md\nfile2.md\nfile10.txt\n'
 
 
+def test_natural_order_by_extension_is_deterministic():
+    """Regression test: natural-extension must be deterministic when
+    multiple files share the same extension.
+
+    The original bug: if the filesystem returned file2.md before file1.md,
+    the stable sort kept them in that order because both had the same
+    key (.md). The result depended on the filesystem's file ordering.
+
+    The fix: use (extension, name) as a composite key to break ties.
+    """
+    # Feed paths in the "wrong" order directly to sort_paths,
+    # bypassing any filesystem/glob ordering entirely.
+    paths = ['file2.md', 'file10.txt', 'file1.md']
+
+    result = sort_paths(paths, order=(False, 'natural', 'extension'))
+    assert result == ['file1.md', 'file2.md', 'file10.txt']
+
+    # Same in reverse
+    paths = ['file2.md', 'file10.txt', 'file1.md']
+    result = sort_paths(paths, order=(True, 'natural', 'extension'))
+    assert result == ['file10.txt', 'file2.md', 'file1.md']
+
+
 @parametrize_directives
 @pytest.mark.parametrize('order_value', ('alpha-name', 'name'))
 def test_alpha_order_by_name(directive, order_value, page, tmp_path, plugin):
@@ -524,7 +548,7 @@ def test_natural_order_by_extension_reverse(directive, page, tmp_path, plugin):
         page(tmp_path / 'includer.md'),
         tmp_path,
         plugin,
-    ) == 'file10.txt\nfile1.md\nfile2.md\n'
+    ) == 'file10.txt\nfile2.md\nfile1.md\n'
 
 
 @parametrize_directives