From 14c4674e45717482d77578097fce39213958909c Mon Sep 17 00:00:00 2001 From: squidfunk Date: Tue, 20 Dec 2022 22:44:07 +0100 Subject: [PATCH] Documentation --- CHANGELOG | 5 +++++ docs/insiders/changelog.md | 5 +++++ docs/insiders/index.md | 7 +++++-- docs/reference/index.md | 4 ++-- docs/schema/plugins/blog.json | 14 ++++++++++++++ docs/setup/setting-up-a-blog.md | 34 ++++++++++++++++++++++++++++++--- docs/setup/setting-up-tags.md | 2 +- 7 files changed, 63 insertions(+), 8 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index eaf07456a..db6a3b244 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,8 @@ +mkdocs-material-8.5.11+insiders-4.27.0 (2022-12-21) + + * 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/docs/insiders/changelog.md b/docs/insiders/changelog.md index 94b73d969..9f28932a9 100644 --- a/docs/insiders/changelog.md +++ b/docs/insiders/changelog.md @@ -2,6 +2,11 @@ ## Material for MkDocs Insiders +### 4.27.0 _ December 21, 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..5aa5a4712 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 21, 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] @@ -295,10 +296,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/reference/index.md b/docs/reference/index.md index 49a90db22..ea933321d 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -7,7 +7,7 @@ within Markdown files. ## Configuration -### Built-in typeset plugin +### Built-in typeset plugin :material-alert-decagram:{ .mdx-pulse title="Added on December 21, 2022" } [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · [:octicons-tag-24: insiders-4.27.0][Insiders] · @@ -198,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] · diff --git a/docs/schema/plugins/blog.json b/docs/schema/plugins/blog.json index 8ad54ff67..c877a3e36 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