From de0fc512e963f75226f8850d9cffbcf1a6e98a3f Mon Sep 17 00:00:00 2001 From: squidfunk Date: Mon, 21 Aug 2023 18:54:53 +0200 Subject: [PATCH] Documentation --- docs/reference/annotations.md | 4 +- docs/reference/index.md | 8 ++-- docs/schema/plugins/blog.json | 8 +++- docs/setup/setting-up-a-blog.md | 64 +++++++++++++++++++--------- docs/setup/setting-up-navigation.md | 4 +- docs/setup/setting-up-site-search.md | 4 +- 6 files changed, 61 insertions(+), 31 deletions(-) diff --git a/docs/reference/annotations.md b/docs/reference/annotations.md index f9e470da2..f625a9e54 100644 --- a/docs/reference/annotations.md +++ b/docs/reference/annotations.md @@ -75,7 +75,7 @@ Some popular choices: ### Using annotations -[:octicons-tag-24: 9.2.0b0][Annotation support] · +[:octicons-tag-24: 9.2.0][Annotation support] · :octicons-beaker-24: Experimental Annotations consist of two parts: a marker, which can be placed anywhere in @@ -104,7 +104,7 @@ Note that the `annotate` class must only be added to the outermost block. All nested elements can use the same list to define annotations, except when annotations are nested themselves. - [Annotation support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0 + [Annotation support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0 #### in annotations diff --git a/docs/reference/index.md b/docs/reference/index.md index 6b7035779..3e9edefbb 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -121,7 +121,7 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)! ### Setting the page `icon` -[:octicons-tag-24: 9.2.0b0][Page icon support] · +[:octicons-tag-24: 9.2.0][Page icon support] · :octicons-beaker-24: Experimental An icon can be assigned to each page, which is then rendered as part of the @@ -149,14 +149,14 @@ icon: material/emoticon-happy # (1)! - [Page icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0 + [Page icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0 [Insiders]: ../insiders/index.md [icon search]: icons-emojis.md#search [navigation tabs]: ../setup/setting-up-navigation.md#navigation-tabs ### Setting the page `status` -[:octicons-tag-24: 9.2.0b0][Page status support] · +[:octicons-tag-24: 9.2.0][Page status support] · :octicons-beaker-24: Experimental A status can be assigned to each page, which is then displayed as part of the @@ -197,7 +197,7 @@ The following status identifiers are currently supported: - :material-alert-decagram: – `new` - :material-trash-can: – `deprecated` - [Page status support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0 + [Page status support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0 ### Setting the page `subtitle` diff --git a/docs/schema/plugins/blog.json b/docs/schema/plugins/blog.json index 380e63e9a..070fd839f 100644 --- a/docs/schema/plugins/blog.json +++ b/docs/schema/plugins/blog.json @@ -33,6 +33,12 @@ "type": "boolean", "default": false }, + "post_dir": { + "title": "Blog posts directory", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_dir", + "type": "string", + "default": "\"{blog}/posts\"" + }, "post_date_format": { "title": "Format string for post dates", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_date_format", @@ -329,7 +335,7 @@ "title": "Authors file", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors_file", "type": "string", - "default": ".authors.yml" + "default": "\"{blog}/.authors.yml\"" }, "draft": { "title": "Render posts marked as drafts", diff --git a/docs/setup/setting-up-a-blog.md b/docs/setup/setting-up-a-blog.md index 7259b9d93..3542aacc7 100644 --- a/docs/setup/setting-up-a-blog.md +++ b/docs/setup/setting-up-a-blog.md @@ -19,7 +19,7 @@ __Check out our [blog], which is created with the new [built-in blog plugin]!__ ### Built-in blog plugin -[:octicons-tag-24: 9.2.0b0][Blog plugin support] · +[:octicons-tag-24: 9.2.0][Blog plugin support] · :octicons-cpu-24: Plugin · :octicons-beaker-24: Experimental @@ -126,7 +126,7 @@ back here later for fine-tuning the output.__ --- - [Blog plugin support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0 + [Blog plugin support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0 [Insiders]: ../insiders/index.md [built-in plugins]: ../insiders/getting-started.md#built-in-plugins [this is configurable]: #+blog.blog_dir @@ -138,6 +138,22 @@ back here later for fine-tuning the output.__ The following configuration options are available for posts: +[`post_dir`](#+blog.post_dir){ #+blog.post_dir } + +: :octicons-milestone-24: Default: `{blog}/posts` – This option specifies + the name of the folder in which the blog plugin should look for posts. + The default settings assumes that the folder is called `posts`: + + ``` yaml + plugins: + - blog: + post_dir: blog/posts + ``` + + The path must be defined relative to [`docs_dir`][docs_dir]. Note that the + `{blog}` placeholder is replaced with the value specified in + [`blog_dir`][this is configurable]. + [`post_date_format`](#+blog.post_date_format){ #+blog.post_date_format } : :octicons-milestone-24: Default: `long` – This option specifies the date @@ -689,7 +705,7 @@ The following configuration options are available for index pagination: pagination_url_format: "{page}" ``` -[`pagination_template`](#+blog.pagination_template){ #+blog.pagination_template } +[`pagination_format`](#+blog.pagination_format){ #+blog.pagination_format } : :octicons-milestone-24: Default: `~2~` – This option specifies the format string that is provided to the [paginate] module, which allows to customize @@ -700,7 +716,7 @@ The following configuration options are available for index pagination: ``` yaml plugins: - blog: - pagination_template: "~2~" + pagination_format: "~2~" ``` === "1 2 3 .. n :material-chevron-right: :material-chevron-double-right:" @@ -708,7 +724,7 @@ The following configuration options are available for index pagination: ``` yaml plugins: - blog: - pagination_template: "$link_first $link_previous ~2~ $link_next $link_last" + pagination_format: "$link_first $link_previous ~2~ $link_next $link_last" ``` === "1 :material-chevron-right:" @@ -716,7 +732,7 @@ The following configuration options are available for index pagination: ``` yaml plugins: - blog: - pagination_template: "$link_previous $page $link_next" + pagination_format: "$link_previous $page $link_next" ``` The [paginate] module exposes the following placeholders: @@ -736,6 +752,18 @@ The following configuration options are available for index pagination: [paginate]: https://pypi.org/project/paginate/ +[`pagination_if_single_page`](#+blog.pagination_if_single_page){ #+blog.pagination_if_single_page } + +: :octicons-milestone-24: Default: `false` – This option specifies whether + the pagination should also be rendered if all posts fit into a single page. + If you wish to always render pagination, add: + + ``` yaml + plugins: + - blog: + pagination_if_single_page: true + ``` + [`pagination_keep_content`](#+blog.pagination_keep_content){ #+blog.pagination_keep_content } : :octicons-milestone-24: Default: `false` – This option specifies whether @@ -767,10 +795,10 @@ The following configuration options are available for author info: [`authors_file`](#+blog.authors_file){ #+blog.authors_file } -: :octicons-milestone-24: Default: `.authors.yml` – This option specifies the - name of the file where the authors for your posts resides. The default - settings assumes that the file is called `.authors.yml` (mind the `.` at - the beginning): +: :octicons-milestone-24: Default: `{blog}/.authors.yml` – This option + specifies the name of the file where the authors for your posts resides. + The default settings assumes that the file is called `.authors.yml` + (mind the `.` at the beginning): ``` yaml plugins: @@ -778,8 +806,9 @@ The following configuration options are available for author info: authors_file: blog/.authors.yml ``` - The path must be defined relative to [`docs_dir`][docs_dir]. - Also see the section on [adding authors]. + The path must be defined relative to [`docs_dir`][docs_dir]. Note that the + `{blog}` placeholder is replaced with the value specified in + [`blog_dir`][this is configurable]. Also see the section on [adding authors]. [adding authors]: #adding-authors @@ -840,8 +869,7 @@ The following configuration options are available for drafts: ### RSS -[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · -[:octicons-tag-24: insiders-4.23.0][Insiders] · +[:octicons-tag-24: 9.2.0][Blog plugin support] · [:octicons-cpu-24: Plugin][rss] The [built-in blog plugin] integrates seamlessly with the [RSS plugin][rss], @@ -1359,14 +1387,10 @@ which means you can override all templates used for the blog by using The following templates are added by the [built-in blog plugin]: -- [`blog.html`][blog.html] – Template for blog index +- [`blog.html`][blog.html] – Template for blog, archive and category index - [`blog-post.html`][blog-post.html] – Template for blog post -- [`blog-archive.html`][blog-archive.html] – Template for blog archive index -- [`blog-category.html`][blog-category.html] – Template for blog category index [theme extension]: ../customization.md#extending-the-theme [blog.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog.html - [blog-post.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-post.html - [blog-archive.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-archive.html - [blog-category.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-category.html + [blog-post.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-post.htmlhtml diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md index 7de159f3d..72d0f14b0 100644 --- a/docs/setup/setting-up-navigation.md +++ b/docs/setup/setting-up-navigation.md @@ -223,7 +223,7 @@ theme: ### Navigation pruning -[:octicons-tag-24: 9.2.0b0][Navigation pruning support] · +[:octicons-tag-24: 9.2.0][Navigation pruning support] · :octicons-beaker-24: Experimental When pruning is enabled, only the visible navigation items are included in the @@ -245,7 +245,7 @@ This feature flag is especially useful for documentation sites with 100+ or even Navigation pruning will replace all expandable sections with links to the first page in that section (or the section index page). - [Navigation pruning support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0 + [Navigation pruning support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0 [navigation.expand]: #navigation-expansion ### Section index pages diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index c05c6b2cd..8ed79f602 100644 --- a/docs/setup/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -191,7 +191,7 @@ The following configuration options are supported: #### Chinese language support -[:octicons-tag-24: 9.2.0b0][Chinese language support] · +[:octicons-tag-24: 9.2.0][Chinese language support] · :octicons-beaker-24: Experimental In order to add support for Chinese languages to the [built-in search plugin], @@ -236,7 +236,7 @@ The following configuration options are available: User dictionaries can be used for tuning the segmenter to preserve technical terms. - [Chinese language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0 + [Chinese language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0 [chinese search]: ../blog/posts/chinese-search-support.md [jieba]: https://pypi.org/project/jieba/ [built-in search plugin]: #built-in-search-plugin