Fixed non-deterministic order of categories in blog plugin

Author: squidfunk

material/plugins/blog/plugin.py

@@ -138,13 +138,17 @@ def on_files(self, files, *, config):
 
         # Generate views for archive
         if self.config.archive:
-            views = self._generate_archive(config, files)
-            self.blog.views.extend(views)
+            self.blog.views.extend(
+                self._generate_archive(config, files)
+            )
 
         # Generate views for categories
         if self.config.categories:
-            views = self._generate_categories(config, files)
-            self.blog.views.extend(views)
+            self.blog.views.extend(sorted(
+                self._generate_categories(config, files),
+                key = lambda view: view.name,
+                reverse = False
+            ))
 
         # Generate pages for views
         if self.config.pagination:
@@ -573,10 +577,9 @@ def _generate_archive(self, config: MkDocsConfig, files: Files):
                 self._save_to_file(file.abs_src_path, f"# {name}")
                 file.inclusion = InclusionLevel.EXCLUDED
 
-            # Create and yield view - we don't explicitly set the title of
-            # the view, so authors can override them in the page's content
+            # Create and yield view
             if not isinstance(file.page, Archive):
-                yield Archive(None, file, config)
+                yield Archive(name, file, config)
 
             # Assign post to archive
             assert isinstance(file.page, Archive)
@@ -610,10 +613,9 @@ def _generate_categories(self, config: MkDocsConfig, files: Files):
                     self._save_to_file(file.abs_src_path, f"# {name}")
                     file.inclusion = InclusionLevel.EXCLUDED
 
-                # Create and yield view - we don't explicitly set the title of
-                # the view, so authors can override them in the page's content
+                # Create and yield view
                 if not isinstance(file.page, Category):
-                    yield Category(None, file, config)
+                    yield Category(name, file, config)
 
                 # Assign post to category and vice versa
                 assert isinstance(file.page, Category)

material/plugins/blog/structure/__init__.py

@@ -212,10 +212,18 @@ def render(self, page: Page, separator: str):
 # View
 class View(Page):
 
+    # Parent view
+    parent: View | Section
+
     # Initialize view
-    def __init__(self, title: str | None, file: File, config: MkDocsConfig):
-        super().__init__(title, file, config)
-        self.parent: View | Section
+    def __init__(self, name: str | None, file: File, config: MkDocsConfig):
+        super().__init__(None, file, config)
+
+        # Initialize name of the view - note that views never pass a title to
+        # the parent constructor, so the author can always override the title
+        # that is used for rendering. However, for some purposes, like for
+        # example sorting, we need something to compare.
+        self.name = name
 
         # Initialize posts and views
         self.posts: list[Post] = []

src/plugins/blog/plugin.py

@@ -138,13 +138,17 @@ def on_files(self, files, *, config):
 
         # Generate views for archive
         if self.config.archive:
-            views = self._generate_archive(config, files)
-            self.blog.views.extend(views)
+            self.blog.views.extend(
+                self._generate_archive(config, files)
+            )
 
         # Generate views for categories
         if self.config.categories:
-            views = self._generate_categories(config, files)
-            self.blog.views.extend(views)
+            self.blog.views.extend(sorted(
+                self._generate_categories(config, files),
+                key = lambda view: view.name,
+                reverse = False
+            ))
 
         # Generate pages for views
         if self.config.pagination:
@@ -573,10 +577,9 @@ def _generate_archive(self, config: MkDocsConfig, files: Files):
                 self._save_to_file(file.abs_src_path, f"# {name}")
                 file.inclusion = InclusionLevel.EXCLUDED
 
-            # Create and yield view - we don't explicitly set the title of
-            # the view, so authors can override them in the page's content
+            # Create and yield view
             if not isinstance(file.page, Archive):
-                yield Archive(None, file, config)
+                yield Archive(name, file, config)
 
             # Assign post to archive
             assert isinstance(file.page, Archive)
@@ -610,10 +613,9 @@ def _generate_categories(self, config: MkDocsConfig, files: Files):
                     self._save_to_file(file.abs_src_path, f"# {name}")
                     file.inclusion = InclusionLevel.EXCLUDED
 
-                # Create and yield view - we don't explicitly set the title of
-                # the view, so authors can override them in the page's content
+                # Create and yield view
                 if not isinstance(file.page, Category):
-                    yield Category(None, file, config)
+                    yield Category(name, file, config)
 
                 # Assign post to category and vice versa
                 assert isinstance(file.page, Category)

src/plugins/blog/structure/__init__.py

@@ -212,10 +212,18 @@ def render(self, page: Page, separator: str):
 # View
 class View(Page):
 
+    # Parent view
+    parent: View | Section
+
     # Initialize view
-    def __init__(self, title: str | None, file: File, config: MkDocsConfig):
-        super().__init__(title, file, config)
-        self.parent: View | Section
+    def __init__(self, name: str | None, file: File, config: MkDocsConfig):
+        super().__init__(None, file, config)
+
+        # Initialize name of the view - note that views never pass a title to
+        # the parent constructor, so the author can always override the title
+        # that is used for rendering. However, for some purposes, like for
+        # example sorting, we need something to compare.
+        self.name = name
 
         # Initialize posts and views
         self.posts: list[Post] = []