1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-12 01:50:52 +01:00

Updated Insiders changelog and blog plugin documentation

This commit is contained in:
squidfunk 2022-09-27 15:37:26 +02:00
parent ab5046d9ff
commit b1b401d5ae
6 changed files with 146 additions and 34 deletions

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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] ·

View File

@ -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",

View File

@ -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,