Updated Insiders changelog and blog plugin documentation

CHANGELOG

@@ -1,3 +1,13 @@
+mkdocs-material-8.5.3+insiders-4.24.0 (2022-09-27)
+
+  * Added support for custom content on index pages (blog)
+  * Added support for keeping content on paginated index pages (blog)
+  * Added support for limiting categories in post excerpts (blog)
+  * Added support for simple override of templates via front matter (blog)
+  * Added icon in navigation for pages with encrypted content
+  * Fixed #4396: Front matter of index pages not inherited by pagination (blog)
+  * Improved performance by building post excerpts once (blog)
+
 mkdocs-material-8.5.3+insiders-4.23.6 (2022-09-22)
 
   * Fixed #4389: Blog posts in first week of year in wrong archive

docs/insiders/changelog.md

@@ -6,6 +6,16 @@ template: overrides/main.html
 
 ## Material for MkDocs Insiders
 
+### 4.24.0 <small>_ September 27, 2022</small> { id="4.24.0" }
+
+- Added support for custom content on index pages (blog)
+- Added support for keeping content on paginated index pages (blog)
+- Added support for limiting categories in post excerpts (blog)
+- Added support for simple override of templates via front matter (blog)
+- Added icon in navigation for pages with encrypted content
+- Fixed #4396: Front matter of index pages not inherited by pagination (blog)
+- Improved performance by building post excerpts once (blog)
+
 ### 4.23.6 <small>_ September 22, 2022</small> { id="4.23.6" }
 
 - Fixed #4389: Blog posts in first week of year in wrong archive

docs/insiders/index.md

@@ -82,15 +82,16 @@ a handful of them, [thanks to our awesome sponsors]!
 ## What's in for me?
 
 The moment you [become a sponsor][how to become a sponsor], you'll get __immediate
-access to 21 additional features__ that you can start using right away, and
+access to 22 additional features__ that you can start using right away, and
 which are currently exclusively available to sponsors:
 
 <div class="mdx-columns" markdown>
 
-- [x] [Blog plugin] :material-alert-decagram:{ .mdx-pulse title="Added on September 12, 2022" }
+- [x] [Blog plugin: custom index pages] :material-alert-decagram:{ .mdx-pulse title="Added on September 27, 2022" }
 - [x] [Blog plugin: related links] :material-alert-decagram:{ .mdx-pulse title="Added on September 12, 2022" }
+- [x] [Blog plugin] :material-alert-decagram:{ .mdx-pulse title="Added on September 12, 2022" }
 - [x] [Navigation status] :material-alert-decagram:{ .mdx-pulse title="Added on August 21, 2022" }
-- [x] [Meta plugin] :material-alert-decagram:{ .mdx-pulse title="Added on July 17, 2022" }
+- [x] [Meta plugin]
 - [x] [Tags plugin: additional indexes]
 - [x] [Document contributors]
 - [x] [Automatic light / dark mode]
@@ -286,15 +287,16 @@ are released for general availability.
 
 - [x] [Meta plugin]
 - [x] [Blog plugin: related links]
+- [x] [Blog plugin: custom index pages]
 - [x] [Tags plugin: additional indexes]
 - [ ] [Instant previews]
 - [ ] Navigation subtitles
-- [ ] ... more to be announced
 
   [Meta plugin]: ../reference/index.md#built-in-meta-plugin
   [Tags plugin: additional indexes]: ../setup/setting-up-tags.md#+tags.tags_extra_files
   [Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743
   [Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links
+  [Blog plugin: custom index pages]: ../setup/setting-up-a-blog.md#custom-index-pages
 
 ### Goals completed
 

docs/reference/index.md

@@ -11,7 +11,7 @@ within Markdown files.
 
 ## Configuration
 
-### Built-in meta plugin :material-alert-decagram:{ .mdx-pulse title="Added on July 17, 2022" }
+### Built-in meta plugin
 
 [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
 [:octicons-tag-24: insiders-4.21.0][Insiders] ·

docs/schema/plugins/blog.json

@@ -113,6 +113,18 @@
               ],
               "default": "optional"
             },
+            "post_excerpt_max_authors": {
+              "title": "Number of authors to render in post excerpts",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt_max_authors",
+              "type": "number",
+              "default": 1
+            },
+            "post_excerpt_max_categories": {
+              "title": "Number of categories to render in post excerpts",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt_max_categories",
+              "type": "number",
+              "default": 5
+            },
             "post_excerpt_separator": {
               "title": "Post excerpt separator",
               "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt_separator",
@@ -281,6 +293,12 @@
               ],
               "default": "~2~"
             },
+            "pagination_keep_content": {
+              "title": "Paginated indexes inherit content",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_keep_content",
+              "type": "boolean",
+              "default": false
+            },
             "authors": {
               "title": "Author info",
               "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors",
@@ -293,12 +311,6 @@
               "type": "string",
               "default": ".authors.yml"
             },
-            "authors_in_excerpt": {
-              "title": "Number of authors to render in post excerpts",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors_in_excerpt",
-              "type": "number",
-              "default": 1
-            },
             "draft": {
               "title": "Render posts marked as drafts",
               "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft",

docs/setup/setting-up-a-blog.md

@@ -294,6 +294,42 @@ The following configuration options are available for posts:
               post_excerpt: required
         ```
 
+[`post_excerpt_max_authors`](#+blog.post_excerpt_max_authors){ #+blog.post_excerpt_max_authors }
+
+:   :octicons-milestone-24: Default: `1` – This option specifies the number of
+    authors rendered in post excerpts. While each post may be written by
+    multiple authors, this setting allows to limit the display to just a few or
+    even a single author, or disable authors in excerpts altogether:
+
+    === "Render up to 2 authors in excerpts"
+
+        ``` yaml
+        plugins:
+          - blog:
+              post_excerpt_max_authors: 2
+        ```
+
+    === "Disable authors in excerpts"
+
+        ``` yaml
+        plugins:
+          - blog:
+              post_excerpt_max_authors: 0
+        ```
+
+[`post_excerpt_max_categories`](#+blog.post_excerpt_max_categories){ #+blog.post_excerpt_max_categories }
+
+:   :octicons-milestone-24: Default: `5` – This option specifies the number of
+    categories rendered in post excerpts. While each post may be assigned to
+    multiple categories, the [built-in blog plugin] can be instructed to only
+    show the first `n` categories to keep it short and concise:
+
+    ``` yaml
+    plugins:
+      - blog:
+          post_excerpt_max_categories: 5
+    ```
+
 [`post_excerpt_separator`](#+blog.post_excerpt_separator){ #+blog.post_excerpt_separator }
 
 :   :octicons-milestone-24: Default: `<!-- more -->` – This option specifies
@@ -634,6 +670,18 @@ The following configuration options are available for index pagination:
 
   [paginate]: https://pypi.org/project/paginate/
 
+[`pagination_keep_content`](#+blog.pagination_keep_content){ #+blog.pagination_keep_content }
+
+:   :octicons-milestone-24: Default: `false` – This option specifies whether
+    paginated index pages should inherit the custom content from the index
+    page, i.e. the content of `blog/index.md`:
+
+    ``` yaml
+    plugins:
+      - blog:
+          pagination_keep_content: true
+    ```
+
 #### Authors
 
 The following configuration options are available for author info:
@@ -667,29 +715,6 @@ The following configuration options are available for author info:
     The path must be defined relative to [`blog_dir`][this is configurable].
     Also see the section on [adding authors].
 
-[`authors_in_excerpt`](#+blog.authors_in_excerpt){ #+blog.authors_in_excerpt }
-
-:   :octicons-milestone-24: Default: `1` – This option specifies the number of
-    authors rendered in post excerpts. While each post may be written by
-    multiple authors, this setting allows to limit the display to just a few or
-    even a single author, or disable authors in excerpts altogether:
-
-    === "Render up to 2 authors in excerpts"
-
-        ``` yaml
-        plugins:
-          - blog:
-              authors_in_excerpt: 2
-        ```
-
-    === "Disable authors in excerpts"
-
-        ``` yaml
-        plugins:
-          - blog:
-              authors_in_excerpt: 0
-        ```
-
   [adding authors]: #adding-authors
 
 #### Drafts
@@ -1198,6 +1223,59 @@ nav:
 
 ## Customization
 
+### Custom index pages
+
+[:octicons-tag-24: insiders-4.24.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+If you want to add custom content to automatically generated [archive] and 
+[category] indexes, e.g. to add a category description prior to the list of
+posts, you can manually create the category page in the same location where
+the [built-in blog plugin] would create it:
+
+``` sh
+.
+├─ docs/
+│  └─ blog/
+│     ├─ category/
+│     │  └─ hello.md #(1)!
+│     ├─ posts/
+│     └─ index.md
+└─ mkdocs.yml
+```
+
+1.  The easiest way is to first [add the category] to the blog post, then take
+    the URL generated by the [built-in blog plugin] and create the file at the
+    corresponding location in the [`blog_dir`][this is configurable] folder.
+
+    Note that the shown directory listing is based on the default configuration.
+    If you specify different values for the following options, be sure to adjust
+    the path accordingly:
+
+    - [`blog_dir`][this is configurable]
+    - [`categories_url_format`][categories_url_format]
+    - [`categories_slugify`][categories_slugify]
+
+You can now add arbitrary content to the newly created file, or set specific
+page properties for this page via front matter, e.g. to change the
+[page description]:
+
+``` yaml
+---
+description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
+---
+
+# Hello
+...
+```
+
+All posts belonging to the category will be automatically appended.
+
+  [add the category]: #adding-categories
+  [page description]: ../reference/index.md#setting-the-page-description
+  [categories_url_format]: #+blog.categories_url_format
+  [categories_slugify]: #+blog.categories_slugify
+
 ### Overriding templates
 
 The [built-in blog plugin] is built on the same basis as Material for MkDocs,