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:
parent
ab5046d9ff
commit
b1b401d5ae
10
CHANGELOG
10
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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
||||
|
@ -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] ·
|
||||
|
@ -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",
|
||||
|
@ -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,
|
||||
|
Loading…
Reference in New Issue
Block a user