@@ -294,6 +294,42 @@ The following configuration options are available for posts:
294294 post_excerpt: required
295295 ` ` `
296296
297+ [`post_excerpt_max_authors`](#+blog.post_excerpt_max_authors){ # +blog.post_excerpt_max_authors }
298+
299+ : :octicons-milestone-24 : Default: `1` – This option specifies the number of
300+ authors rendered in post excerpts. While each post may be written by
301+ multiple authors, this setting allows to limit the display to just a few or
302+ even a single author, or disable authors in excerpts altogether :
303+
304+ === "Render up to 2 authors in excerpts"
305+
306+ ` ` ` yaml
307+ plugins:
308+ - blog:
309+ post_excerpt_max_authors: 2
310+ ` ` `
311+
312+ === "Disable authors in excerpts"
313+
314+ ` ` ` yaml
315+ plugins:
316+ - blog:
317+ post_excerpt_max_authors: 0
318+ ` ` `
319+
320+ [`post_excerpt_max_categories`](#+blog.post_excerpt_max_categories){ # +blog.post_excerpt_max_categories }
321+
322+ : :octicons-milestone-24 : Default: `5` – This option specifies the number of
323+ categories rendered in post excerpts. While each post may be assigned to
324+ multiple categories, the [built-in blog plugin] can be instructed to only
325+ show the first `n` categories to keep it short and concise :
326+
327+ ` ` ` yaml
328+ plugins:
329+ - blog:
330+ post_excerpt_max_categories: 5
331+ ` ` `
332+
297333[`post_excerpt_separator`](#+blog.post_excerpt_separator){ # +blog.post_excerpt_separator }
298334
299335: :octicons-milestone-24 : Default: `<!-- more -->` – This option specifies
@@ -634,6 +670,18 @@ The following configuration options are available for index pagination:
634670
635671 [paginate] : https://pypi.org/project/paginate/
636672
673+ [`pagination_keep_content`](#+blog.pagination_keep_content){ # +blog.pagination_keep_content }
674+
675+ : :octicons-milestone-24 : Default: `false` – This option specifies whether
676+ paginated index pages should inherit the custom content from the index
677+ page, i.e. the content of `blog/index.md` :
678+
679+ ` ` ` yaml
680+ plugins:
681+ - blog:
682+ pagination_keep_content: true
683+ ` ` `
684+
637685# ### Authors
638686
639687The following configuration options are available for author info :
@@ -667,29 +715,6 @@ The following configuration options are available for author info:
667715 The path must be defined relative to [`blog_dir`][this is configurable].
668716 Also see the section on [adding authors].
669717
670- [`authors_in_excerpt`](#+blog.authors_in_excerpt){ # +blog.authors_in_excerpt }
671-
672- : :octicons-milestone-24 : Default: `1` – This option specifies the number of
673- authors rendered in post excerpts. While each post may be written by
674- multiple authors, this setting allows to limit the display to just a few or
675- even a single author, or disable authors in excerpts altogether :
676-
677- === "Render up to 2 authors in excerpts"
678-
679- ` ` ` yaml
680- plugins:
681- - blog:
682- authors_in_excerpt: 2
683- ` ` `
684-
685- === "Disable authors in excerpts"
686-
687- ` ` ` yaml
688- plugins:
689- - blog:
690- authors_in_excerpt: 0
691- ` ` `
692-
693718 [adding authors] : # adding-authors
694719
695720# ### Drafts
@@ -1198,6 +1223,59 @@ nav:
11981223
11991224# # Customization
12001225
1226+ # ## Custom index pages
1227+
1228+ [:octicons-tag-24 : insiders-4.24.0][Insiders] ·
1229+ :octicons-beaker-24 : Experimental
1230+
1231+ If you want to add custom content to automatically generated [archive] and
1232+ [category] indexes, e.g. to add a category description prior to the list of
1233+ posts, you can manually create the category page in the same location where
1234+ the [built-in blog plugin] would create it :
1235+
1236+ ` ` ` sh
1237+ .
1238+ ├─ docs/
1239+ │ └─ blog/
1240+ │ ├─ category/
1241+ │ │ └─ hello.md #(1)!
1242+ │ ├─ posts/
1243+ │ └─ index.md
1244+ └─ mkdocs.yml
1245+ ` ` `
1246+
1247+ 1. The easiest way is to first [add the category] to the blog post, then take
1248+ the URL generated by the [built-in blog plugin] and create the file at the
1249+ corresponding location in the [`blog_dir`][this is configurable] folder.
1250+
1251+ Note that the shown directory listing is based on the default configuration.
1252+ If you specify different values for the following options, be sure to adjust
1253+ the path accordingly :
1254+
1255+ - [`blog_dir`][this is configurable]
1256+ - [`categories_url_format`][categories_url_format]
1257+ - [`categories_slugify`][categories_slugify]
1258+
1259+ You can now add arbitrary content to the newly created file, or set specific
1260+ page properties for this page via front matter, e.g. to change the
1261+ [page description] :
1262+
1263+ ` ` ` yaml
1264+ ---
1265+ description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
1266+ ---
1267+
1268+ # Hello
1269+ ...
1270+ ` ` `
1271+
1272+ All posts belonging to the category will be automatically appended.
1273+
1274+ [add the category] : # adding-categories
1275+ [page description] : ../reference/index.md#setting-the-page-description
1276+ [categories_url_format] : # +blog.categories_url_format
1277+ [categories_slugify] : # +blog.categories_slugify
1278+
12011279# ## Overriding templates
12021280
12031281The [built-in blog plugin] is built on the same basis as Material for MkDocs,
0 commit comments