diff --git a/.github/assets/sponsors/sponsor-rackn.png b/.github/assets/sponsors/sponsor-rackn.png
new file mode 100644
index 000000000..77bf33dc2
Binary files /dev/null and b/.github/assets/sponsors/sponsor-rackn.png differ
diff --git a/CHANGELOG b/CHANGELOG
index eaf07456a..763331419 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -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)
* Let it snow, see https://twitter.com/squidfunk/status/1597939243090788352
diff --git a/README.md b/README.md
index ffbf2e6d0..362de9f31 100644
--- a/README.md
+++ b/README.md
@@ -146,6 +146,9 @@
+ 
diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md
index d8f24664e..4fc90ff28 100644
--- a/docs/creating-your-site.md
+++ b/docs/creating-your-site.md
@@ -78,8 +78,8 @@ theme:
=== "Other"
- 3. Ensure your editor of choice has support for YAML schema validation.
- 4. Add the following lines at the top of `mkdocs.yml`:
+ 1. Ensure your editor of choice has support for YAML schema validation.
+ 2. Add the following lines at the top of `mkdocs.yml`:
``` yaml
# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md
index 94b73d969..4a3e62dc5 100644
--- a/docs/insiders/changelog.md
+++ b/docs/insiders/changelog.md
@@ -2,6 +2,11 @@
## Material for MkDocs Insiders
+### 4.27.0 _ December 20, 2022 { 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 _ November 28, 2022 { id="4.26.6" }
- Fixed #4683: Tags plugin crashes when a tag is empty
diff --git a/docs/insiders/index.md b/docs/insiders/index.md
index c1cc476b0..d6d18e6b3 100644
--- a/docs/insiders/index.md
+++ b/docs/insiders/index.md
@@ -88,14 +88,15 @@ a handful of them, [thanks to our awesome sponsors]!
## What's in it for me?
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:
+- [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] [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: related links]
- [x] [Blog plugin]
@@ -188,6 +189,7 @@ You can cancel your sponsorship anytime.[^5]
[![SealVault]](https://sealvault.org/){ target=_blank title="SealVault" }
[![Neptune]](https://neptune.ai/){ target=_blank title="Neptune" }
[![Cash App]](https://cash.app/){ target=_blank title="Cash App" }
+[![RackN]](https://rackn.com/){ target=_blank title="RackN" }
@@ -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
[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
+ [RackN]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-rackn.png
@@ -295,10 +298,12 @@ are released for general availability.
#### $ 20,000 – Jalapeño
+- [x] [Typeset plugin]
- [x] [Privacy plugin: external links]
- [ ] [Instant previews]
- ... 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
[Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743
diff --git a/docs/philosophy.md b/docs/philosophy.md
index afdad982b..13960e962 100644
--- a/docs/philosophy.md
+++ b/docs/philosophy.md
@@ -14,7 +14,7 @@ discusses the [conventions] used in this documentation.
– let Material for MkDocs do the heavy lifting for you.
- __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.
- __Made to measure__: Change the colors, fonts, language, icons, logo and much
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 4cd5b6247..fd9b1e224 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -7,6 +7,28 @@ within Markdown files.
## Configuration
+### Built-in typeset 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
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
@@ -49,7 +71,7 @@ The following configuration options are available:
## Usage
-### Setting the page title
+### Setting the page `title`
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
@@ -76,7 +98,7 @@ title: Lorem ipsum dolor sit amet # (1)!
[head]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head
[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 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
-### Setting the page icon
+### Setting the page `icon`
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.5.0][Insiders] ·
@@ -132,7 +154,7 @@ icon: material/emoticon-happy # (1)!
[icon search]: icons-emojis.md#search
[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-tag-24: insiders-4.22.0][Insiders] ·
@@ -176,7 +198,7 @@ The following status identifiers are currently supported:
- :material-alert-decagram: – `new`
- :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-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
`overrides` directory, you can enable it for a specific page. Add the following
@@ -227,7 +249,7 @@ template: custom.html
### 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
][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
-#### 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
values for different pages, you can use the `page.meta` object inside your
diff --git a/docs/schema/plugins/blog.json b/docs/schema/plugins/blog.json
index ec7492776..39548988b 100644
--- a/docs/schema/plugins/blog.json
+++ b/docs/schema/plugins/blog.json
@@ -68,7 +68,9 @@
"oneOf": [
{
"enum": [
+ "\"{date}/{file}\"",
"\"{date}/{slug}\"",
+ "\"{file}\"",
"\"{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": {
"title": "Post slugify function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify",
@@ -233,6 +241,12 @@
"type": "string",
"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": {
"title": "Categories allowed",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_allowed",
diff --git a/docs/setup/setting-up-a-blog.md b/docs/setup/setting-up-a-blog.md
index 9eab7b222..e4291720c 100644
--- a/docs/setup/setting-up-a-blog.md
+++ b/docs/setup/setting-up-a-blog.md
@@ -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
placeholders are currently supported:
+ - `categories` – Replaced with the post's slugified [categories].
+
- `date` – Replaced with the post's date, as configured in
[`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
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 }
: :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 }
: :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
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 }
: :octicons-milestone-24: Default: `category/{slug}` – This option specifies
- the format string that is used for the URL of the category index, and can
- be used to localize the URL:
+ the format string that is used for the URL of a category index, and can be
+ used to localize the URL:
=== ":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_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 }
: :octicons-milestone-24: Default: _none_ – This option specifies the
diff --git a/docs/setup/setting-up-tags.md b/docs/setup/setting-up-tags.md
index 9ef2a659d..8b84cecc6 100644
--- a/docs/setup/setting-up-tags.md
+++ b/docs/setup/setting-up-tags.md
@@ -160,7 +160,7 @@ The following configuration options are available:
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:
Default: _none_ – This option allows the author to define explicitly which
diff --git a/material/partials/languages/it.html b/material/partials/languages/it.html
index 57ed4a175..1b607a216 100644
--- a/material/partials/languages/it.html
+++ b/material/partials/languages/it.html
@@ -5,8 +5,12 @@
"language": "it",
"action.edit": "Modifica",
"action.skip": "Vai al contenuto",
+ "announce.dismiss": "Non mostrare più",
"clipboard.copy": "Copia",
"clipboard.copied": "Copiato",
+ "consent.accept": "Accettazione",
+ "consent.manage": "Gestisci le opzioni",
+ "consent.reject": "Rifiuta",
"footer": "Piede",
"footer.next": "Prossimo",
"footer.previous": "Precedente",
diff --git a/src/partials/languages/it.html b/src/partials/languages/it.html
index af8b0f391..03f5e0a6b 100644
--- a/src/partials/languages/it.html
+++ b/src/partials/languages/it.html
@@ -25,8 +25,12 @@
"language": "it",
"action.edit": "Modifica",
"action.skip": "Vai al contenuto",
+ "announce.dismiss": "Non mostrare più",
"clipboard.copy": "Copia",
"clipboard.copied": "Copiato",
+ "consent.accept": "Accettazione",
+ "consent.manage": "Gestisci le opzioni",
+ "consent.reject": "Rifiuta",
"footer": "Piede",
"footer.next": "Prossimo",
"footer.previous": "Precedente",