Merge branch 'master' into feature/material-v9

This commit is contained in:
squidfunk 2022-12-31 13:24:27 +01:00
commit 85679fd82f
13 changed files with 107 additions and 17 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 10 KiB

View File

@ -1,3 +1,8 @@
mkdocs-material-8.5.11+insiders-4.27.0 (2022-12-20)
* Added built-in typeset plugin to preserve formatting in sidebars
* Added URL and table of contents support for blog categories
mkdocs-material-8.5.11 (2022-11-30) mkdocs-material-8.5.11 (2022-11-30)
* Let it snow, see https://twitter.com/squidfunk/status/1597939243090788352 * Let it snow, see https://twitter.com/squidfunk/status/1597939243090788352

View File

@ -146,6 +146,9 @@
<a href="https://cash.app/" target=_blank><img <a href="https://cash.app/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-cashapp.png" height="58" src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-cashapp.png" height="58"
/></a> /></a>
<a href="https://rackn.com/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-rackn.png" height="58"
/></a>
</p> </p>
<p>&nbsp;</p> <p>&nbsp;</p>

View File

@ -78,8 +78,8 @@ theme:
=== "Other" === "Other"
3. Ensure your editor of choice has support for YAML schema validation. 1. Ensure your editor of choice has support for YAML schema validation.
4. Add the following lines at the top of `mkdocs.yml`: 2. Add the following lines at the top of `mkdocs.yml`:
``` yaml ``` yaml
# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json # yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json

View File

@ -2,6 +2,11 @@
## Material for MkDocs Insiders ## Material for MkDocs Insiders
### 4.27.0 <small>_ December 20, 2022</small> { id="4.27.0" }
- Added built-in typeset plugin to preserve formatting in sidebars
- Added URL and table of contents support for blog categories
### 4.26.6 <small>_ November 28, 2022</small> { id="4.26.6" } ### 4.26.6 <small>_ November 28, 2022</small> { id="4.26.6" }
- Fixed #4683: Tags plugin crashes when a tag is empty - Fixed #4683: Tags plugin crashes when a tag is empty

View File

@ -88,14 +88,15 @@ a handful of them, [thanks to our awesome sponsors]!
## What's in it for me? ## What's in it for me?
The moment you [become a sponsor][how to become a sponsor], you'll get __immediate The moment you [become a sponsor][how to become a sponsor], you'll get __immediate
access to 19 additional features__ that you can start using right away, and access to 20 additional features__ that you can start using right away, and
which are currently exclusively available to sponsors: which are currently exclusively available to sponsors:
<div class="mdx-columns" markdown> <div class="mdx-columns" markdown>
- [x] [Typeset plugin]: :material-alert-decagram:{ .mdx-pulse title="Added on December 20, 2022" }
- [x] [Privacy plugin: external links] :material-alert-decagram:{ .mdx-pulse title="Added on October 18, 2022" } - [x] [Privacy plugin: external links] :material-alert-decagram:{ .mdx-pulse title="Added on October 18, 2022" }
- [x] [Navigation subtitles] :material-alert-decagram:{ .mdx-pulse title="Added on October 2, 2022" } - [x] [Navigation subtitles] :material-alert-decagram:{ .mdx-pulse title="Added on October 2, 2022" }
- [x] [Tags plugin: allow list] + [custom sorting] :material-alert-decagram:{ .mdx-pulse title="Added on October 2, 2022" } - [x] [Tags plugin: allow list] + [custom sorting]
- [x] [Blog plugin: custom index pages] - [x] [Blog plugin: custom index pages]
- [x] [Blog plugin: related links] - [x] [Blog plugin: related links]
- [x] [Blog plugin] - [x] [Blog plugin]
@ -188,6 +189,7 @@ You can cancel your sponsorship anytime.[^5]
[![SealVault]](https://sealvault.org/){ target=_blank title="SealVault" } [![SealVault]](https://sealvault.org/){ target=_blank title="SealVault" }
[![Neptune]](https://neptune.ai/){ target=_blank title="Neptune" } [![Neptune]](https://neptune.ai/){ target=_blank title="Neptune" }
[![Cash App]](https://cash.app/){ target=_blank title="Cash App" } [![Cash App]](https://cash.app/){ target=_blank title="Cash App" }
[![RackN]](https://rackn.com/){ target=_blank title="RackN" }
</div> </div>
@ -218,6 +220,7 @@ You can cancel your sponsorship anytime.[^5]
[SealVault]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-sealvault.png [SealVault]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-sealvault.png
[Neptune]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-neptune-ai.png [Neptune]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-neptune-ai.png
[Cash App]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-cashapp.png [Cash App]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-cashapp.png
[RackN]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-rackn.png
<hr /> <hr />
@ -295,10 +298,12 @@ are released for general availability.
#### $ 20,000 Jalapeño #### $ 20,000 Jalapeño
- [x] [Typeset plugin]
- [x] [Privacy plugin: external links] - [x] [Privacy plugin: external links]
- [ ] [Instant previews] - [ ] [Instant previews]
- ... more to be announced - ... more to be announced
[Typeset plugin]: ../reference/index.md#built-in-typeset-plugin
[Privacy plugin: external links]: ../setup/ensuring-data-privacy.md#+privacy.external_links [Privacy plugin: external links]: ../setup/ensuring-data-privacy.md#+privacy.external_links
[Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743 [Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743

View File

@ -14,7 +14,7 @@ discusses the [conventions] used in this documentation.
let Material for MkDocs do the heavy lifting for you. let Material for MkDocs do the heavy lifting for you.
- __Works on all devices__: Serve your documentation with confidence the - __Works on all devices__: Serve your documentation with confidence the
underling layout automatically adapts to perfectly fit the available screen underlying layout automatically adapts to perfectly fit the available screen
estate, no matter the type or size of the viewing device. estate, no matter the type or size of the viewing device.
- __Made to measure__: Change the colors, fonts, language, icons, logo and much - __Made to measure__: Change the colors, fonts, language, icons, logo and much

View File

@ -7,6 +7,28 @@ within Markdown files.
## Configuration ## Configuration
### Built-in <u>typeset</u> plugin :material-alert-decagram:{ .mdx-pulse title="Added on December 20, 2022" }
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.27.0][Insiders] ·
:octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental
The built-in typeset plugin __preserves HTML formatting__ in the navigation and
table of contents. This means that now, code blocks, icons, emojis and other
inline formatting will be preserved, which allows for a richer editing
experience. Add the following lines to `mkdocs.yml`:
``` yaml
plugins:
- typeset
```
For a demo, just take a look at the table of contents of this page :material-arrow-right-circle: code blocks and icons are preserved from the
section headlines; even [highlighting inline code blocks] is supported :tada:
[highlighting inline code blocks]: code-blocks.md#highlighting-inline-code-blocks
### Built-in meta plugin ### Built-in meta plugin
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
@ -49,7 +71,7 @@ The following configuration options are available:
## Usage ## Usage
### Setting the page title ### Setting the page `title`
Each page has a designated title, which is used in the navigation sidebar, for Each page has a designated title, which is used in the navigation sidebar, for
[social cards] and in other places. While MkDocs attempts to automatically [social cards] and in other places. While MkDocs attempts to automatically
@ -76,7 +98,7 @@ title: Lorem ipsum dolor sit amet # (1)!
[head]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head [head]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head
[site_name]: https://www.mkdocs.org/user-guide/configuration/#site_name [site_name]: https://www.mkdocs.org/user-guide/configuration/#site_name
### Setting the page description ### Setting the page `description`
A Markdown file can include a description that is added to the `meta` tags of A Markdown file can include a description that is added to the `meta` tags of
a page, and is also used for [social cards]. It's a good idea to set a a page, and is also used for [social cards]. It's a good idea to set a
@ -97,7 +119,7 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
[site_description]: https://www.mkdocs.org/user-guide/configuration/#site_description [site_description]: https://www.mkdocs.org/user-guide/configuration/#site_description
### Setting the page icon ### Setting the page `icon`
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.5.0][Insiders] · [:octicons-tag-24: insiders-4.5.0][Insiders] ·
@ -132,7 +154,7 @@ icon: material/emoticon-happy # (1)!
[icon search]: icons-emojis.md#search [icon search]: icons-emojis.md#search
[navigation tabs]: ../setup/setting-up-navigation.md#navigation-tabs [navigation tabs]: ../setup/setting-up-navigation.md#navigation-tabs
### Setting the page status ### Setting the page `status`
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.22.0][Insiders] · [:octicons-tag-24: insiders-4.22.0][Insiders] ·
@ -176,7 +198,7 @@ The following status identifiers are currently supported:
- :material-alert-decagram: `new` - :material-alert-decagram: `new`
- :material-trash-can: `deprecated` - :material-trash-can: `deprecated`
### Setting the page subtitle ### Setting the page `subtitle` :material-alert-decagram:{ .mdx-pulse title="Added on October 2, 2022" }
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.25.0][Insiders] · [:octicons-tag-24: insiders-4.25.0][Insiders] ·
@ -195,7 +217,7 @@ subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor
... ...
``` ```
### Setting the page template ### Setting the page `template`
If you're using [theme extension] and created a new page template in the If you're using [theme extension] and created a new page template in the
`overrides` directory, you can enable it for a specific page. Add the following `overrides` directory, you can enable it for a specific page. Add the following
@ -227,7 +249,7 @@ template: custom.html
### Using metadata in templates ### Using metadata in templates
#### on all pages #### :material-check-all: on all pages
In order to add custom `meta` tags to your document, you can [extend the theme In order to add custom `meta` tags to your document, you can [extend the theme
][theme extension] and [override the `extrahead` block][overriding blocks], ][theme extension] and [override the `extrahead` block][overriding blocks],
@ -243,7 +265,7 @@ e.g. to add indexing policies for search engines via the `robots` property:
[overriding blocks]: ../customization.md#overriding-blocks [overriding blocks]: ../customization.md#overriding-blocks
#### on a single page #### :material-check: on a single page
If you want to set a `meta` tag on a single page, or want to set different If you want to set a `meta` tag on a single page, or want to set different
values for different pages, you can use the `page.meta` object inside your values for different pages, you can use the `page.meta` object inside your

View File

@ -68,7 +68,9 @@
"oneOf": [ "oneOf": [
{ {
"enum": [ "enum": [
"\"{date}/{file}\"",
"\"{date}/{slug}\"", "\"{date}/{slug}\"",
"\"{file}\"",
"\"{slug}\"" "\"{slug}\""
] ]
}, },
@ -77,6 +79,12 @@
} }
] ]
}, },
"post_url_max_categories": {
"title": "Number of categories in post URLs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_url_max_categories",
"type": "number",
"default": 1
},
"post_slugify": { "post_slugify": {
"title": "Post slugify function", "title": "Post slugify function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify",
@ -233,6 +241,12 @@
"type": "string", "type": "string",
"default": "\"-\"" "default": "\"-\""
}, },
"categories_toc": {
"title": "Category index table of contents",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_toc",
"type": "boolean",
"default": false
},
"categories_allowed": { "categories_allowed": {
"title": "Categories allowed", "title": "Categories allowed",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_allowed", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_allowed",

View File

@ -210,6 +210,8 @@ The following configuration options are available for posts:
format string that is used for the URL of the post. The following format string that is used for the URL of the post. The following
placeholders are currently supported: placeholders are currently supported:
- `categories` Replaced with the post's slugified [categories].
- `date` Replaced with the post's date, as configured in - `date` Replaced with the post's date, as configured in
[`post_url_date_format`][post_url_date_format]. [`post_url_date_format`][post_url_date_format].
@ -237,6 +239,20 @@ The following configuration options are available for posts:
collide with other the URLs of other pages added to the blog section, as collide with other the URLs of other pages added to the blog section, as
this leads to undefined behavior. this leads to undefined behavior.
[`post_url_max_categories`](#+blog.post_url_max_categories){ #+blog.post_url_max_categories }
: :octicons-milestone-24: Default: `1` This option specifies the number of
categories that are included in the URL if the `categories` placeholder is
part of [`post_url_format`][post slugs]. If a post is assigned to multiple
categories, they are joined with `/`:
``` yaml
plugins:
- blog:
post_url_format: "{categories}/{slug}"
post_url_max_categories: 2
```
[`post_slugify`](#+blog.post_slugify){ #+blog.post_slugify } [`post_slugify`](#+blog.post_slugify){ #+blog.post_slugify }
: :octicons-milestone-24: Default: `headerid.slugify` This option specifies : :octicons-milestone-24: Default: `headerid.slugify` This option specifies
@ -488,7 +504,7 @@ The following configuration options are available for category index generation:
[`categories`](#+blog.categories){ #+blog.categories } [`categories`](#+blog.categories){ #+blog.categories }
: :octicons-milestone-24: Default: `true` This option specifies whether the : :octicons-milestone-24: Default: `true` This option specifies whether the
[built-in blog plugin] should generate category indexes. A category indexes [built-in blog plugin] should generate category indexes. A category index
shows all posts for a specific category in reverse chronological order. If shows all posts for a specific category in reverse chronological order. If
you want to disable category index generation, add: you want to disable category index generation, add:
@ -514,8 +530,8 @@ The following configuration options are available for category index generation:
[`categories_url_format`](#+blog.categories_url_format){ #+blog.categories_url_format } [`categories_url_format`](#+blog.categories_url_format){ #+blog.categories_url_format }
: :octicons-milestone-24: Default: `category/{slug}` This option specifies : :octicons-milestone-24: Default: `category/{slug}` This option specifies
the format string that is used for the URL of the category index, and can the format string that is used for the URL of a category index, and can be
be used to localize the URL: used to localize the URL:
=== ":material-link: blog/category/:material-dots-horizontal:/" === ":material-link: blog/category/:material-dots-horizontal:/"
@ -570,6 +586,18 @@ The following configuration options are available for category index generation:
categories_slugify_separator: "-" categories_slugify_separator: "-"
``` ```
[`categories_toc`](#+blog.categories_toc){ #+blog.categories_toc }
: :octicons-milestone-24: Default: `false` This option specifies whether a
category index includes a table of contents with all post titles on the
right side as an overview:
``` yaml
plugins:
- blog:
categories_toc: true
```
[`categories_allowed`](#+blog.categories_allowed){ #+blog.categories_allowed } [`categories_allowed`](#+blog.categories_allowed){ #+blog.categories_allowed }
: :octicons-milestone-24: Default: _none_ This option specifies the : :octicons-milestone-24: Default: _none_ This option specifies the

View File

@ -160,7 +160,7 @@ The following configuration options are available:
tags_compare_reverse: true tags_compare_reverse: true
``` ```
[`tags_allowed`](#+tags.tags_allowed){ #+tags.tags_allowed } :material-alert-decagram:{ .mdx-pulse title="Added on October 2, 2022" } [`tags_allowed`](#+tags.tags_allowed){ #+tags.tags_allowed }
: [:octicons-tag-24: insiders-4.25.0][Insiders] · :octicons-milestone-24: : [:octicons-tag-24: insiders-4.25.0][Insiders] · :octicons-milestone-24:
Default: _none_ This option allows the author to define explicitly which Default: _none_ This option allows the author to define explicitly which

View File

@ -5,8 +5,12 @@
"language": "it", "language": "it",
"action.edit": "Modifica", "action.edit": "Modifica",
"action.skip": "Vai al contenuto", "action.skip": "Vai al contenuto",
"announce.dismiss": "Non mostrare più",
"clipboard.copy": "Copia", "clipboard.copy": "Copia",
"clipboard.copied": "Copiato", "clipboard.copied": "Copiato",
"consent.accept": "Accettazione",
"consent.manage": "Gestisci le opzioni",
"consent.reject": "Rifiuta",
"footer": "Piede", "footer": "Piede",
"footer.next": "Prossimo", "footer.next": "Prossimo",
"footer.previous": "Precedente", "footer.previous": "Precedente",

View File

@ -25,8 +25,12 @@
"language": "it", "language": "it",
"action.edit": "Modifica", "action.edit": "Modifica",
"action.skip": "Vai al contenuto", "action.skip": "Vai al contenuto",
"announce.dismiss": "Non mostrare più",
"clipboard.copy": "Copia", "clipboard.copy": "Copia",
"clipboard.copied": "Copiato", "clipboard.copied": "Copiato",
"consent.accept": "Accettazione",
"consent.manage": "Gestisci le opzioni",
"consent.reject": "Rifiuta",
"footer": "Piede", "footer": "Piede",
"footer.next": "Prossimo", "footer.next": "Prossimo",
"footer.previous": "Precedente", "footer.previous": "Precedente",