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,