diff --git a/CHANGELOG b/CHANGELOG
index aa1716551..7bdcf927a 100644
--- a/CHANGELOG
+++ b/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
diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md
index 40722f74b..de2470ef5 100644
--- a/docs/insiders/changelog.md
+++ b/docs/insiders/changelog.md
@@ -6,6 +6,16 @@ template: overrides/main.html
## Material for MkDocs Insiders
+### 4.24.0 _ September 27, 2022 { 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 _ September 22, 2022 { id="4.23.6" }
- Fixed #4389: Blog posts in first week of year in wrong archive
diff --git a/docs/insiders/index.md b/docs/insiders/index.md
index acb712676..e3d4ab720 100644
--- a/docs/insiders/index.md
+++ b/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:
-- [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
diff --git a/docs/reference/index.md b/docs/reference/index.md
index e51bdc5b0..f5e8c8104 100644
--- a/docs/reference/index.md
+++ b/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] ·
diff --git a/docs/schema/plugins/blog.json b/docs/schema/plugins/blog.json
index 97e75231b..530fc427c 100644
--- a/docs/schema/plugins/blog.json
+++ b/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",
diff --git a/docs/setup/setting-up-a-blog.md b/docs/setup/setting-up-a-blog.md
index 9e0840279..b7ab51d15 100644
--- a/docs/setup/setting-up-a-blog.md
+++ b/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: `` – 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,