From c44baee78d5cffec89c5d39c79b6504609795331 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 2 Oct 2022 16:36:47 +0200 Subject: [PATCH] Documentation --- docs/insiders/index.md | 26 +++++--- docs/reference/index.md | 57 ++++++++++++++---- docs/schema/extensions/markdown.json | 2 +- docs/schema/extensions/pymdownx.json | 2 - docs/schema/plugins/blog.json | 6 +- docs/schema/plugins/tags.json | 26 ++++++++ docs/setup/adding-a-comment-system.md | 6 +- docs/setup/adding-a-git-repository.md | 2 +- docs/setup/extensions/python-markdown.md | 4 +- docs/setup/setting-up-a-blog.md | 31 +++++----- docs/setup/setting-up-site-analytics.md | 3 +- docs/setup/setting-up-tags.md | 77 ++++++++++++++++++++++-- 12 files changed, 189 insertions(+), 53 deletions(-) diff --git a/docs/insiders/index.md b/docs/insiders/index.md index 07746aee2..1ac620b63 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -82,15 +82,17 @@ 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 22 additional features__ that you can start using right away, and +access to 24 additional features__ that you can start using right away, and which are currently exclusively available to sponsors:
+- [x] [Navigation subtitles] :material-alert-decagram:{ .mdx-pulse title="Added on October 2, 2022" } +- [x] [Tags plugin: allow list] :material-alert-decagram:{ .mdx-pulse title="Added on October 2, 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] [Blog plugin: related links] +- [x] [Blog plugin] +- [x] [Navigation status] - [x] [Meta plugin] - [x] [Tags plugin: additional indexes] - [x] [Document contributors] @@ -293,14 +295,22 @@ are released for general availability. - [x] [Blog plugin: related links] - [x] [Blog plugin: custom index pages] - [x] [Tags plugin: additional indexes] -- [ ] [Instant previews] -- [ ] Navigation subtitles +- [x] [Tags plugin: allow list] +- [x] [Navigation subtitles] [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 + [Tags plugin: additional indexes]: ../setup/setting-up-tags.md#+tags.tags_extra_files + [Tags plugin: allow list]: ../setup/setting-up-tags.md#+tags.tags_allowed + [Navigation subtitles]: ../reference/index.md#setting-the-page-subtitle + +#### $ 20,000 – Jalapeño + +- [ ] [Instant previews] +- ... more to be announced + + [Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743 ### Goals completed diff --git a/docs/reference/index.md b/docs/reference/index.md index 196d686fb..08e8beb12 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -5,7 +5,7 @@ template: overrides/main.html # Reference Material for MkDocs is packed with many great features that make technical -writing a pleasure. This section of the documentation explains how to set up +writing a joyful activity. This section of the documentation explains how to set up a page, and showcases all available specimen that can be used directly from within Markdown files. @@ -55,8 +55,10 @@ The following configuration options are available: ### Setting the page title -The page title can be overridden for a document with the front matter `title` -property. Add the following lines at the top of a Markdown file: +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 +determine the title of a page in a [four step process], the title can also be +explicitly set with the front matter `title` property: ``` yaml --- @@ -67,18 +69,23 @@ title: Lorem ipsum dolor sit amet # (1)! ... ``` -1. This will set the [`title`][title] inside the HTML document's [`head`][head] - for the generated page to this value. Note that the site title, which is set - via [`site_name`][site_name], is appended with a dash. +1. This line sets the [`title`][title] inside the HTML document's + [`head`][head] for the generated page to the given value. Note that the + site title, which is set via [`site_name`][site_name], is appended with a + dash. + [social cards]: ../setup/setting-up-social-cards.md + [four step process]: https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data [title]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title [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 -The page description can be overridden for a document with the front matter -`description` property. Add the following lines at the top of a Markdown file: +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 +[`site_description`][site_description] in `mkdocs.yml` as a fallback value if +the author does not explicitly define a description for a Markdown file: ``` yaml --- @@ -89,9 +96,11 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)! ... ``` -1. This will set the `meta` tag containing the site description inside the +1. This line sets the `meta` tag containing the description inside the document `head` for the current page to the provided value. + [site_description]: https://www.mkdocs.org/user-guide/configuration/#site_description + ### Setting the page icon [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · @@ -99,7 +108,9 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)! :octicons-beaker-24: Experimental An icon can be assigned to each page, which is then rendered as part of the -navigation sidebar. Add the following lines at the top of a Markdown file: +navigation sidebar, as well as [navigation tabs], if enabled. Use the front +matter `icon` property to reference an icon, adding the following lines at the +top of a Markdown file: ``` yaml --- @@ -123,6 +134,7 @@ icon: material/emoticon-happy # (1)! [Insiders]: ../insiders/index.md [icon search]: icons-emojis.md#search + [navigation tabs]: ../setup/setting-up-navigation.md#navigation-tabs ### Setting the page status @@ -150,9 +162,9 @@ extra: new: Recently added ``` -The page status can now be set for a document with the front matter `status` -property. For example, you can mark a page as `new` with the following lines at -the top of a Markdown file: +The page status can now be set with the front matter `status` property. For +example, you can mark a page as `new` with the following lines at the top of a +Markdown file: ``` yaml --- @@ -168,6 +180,25 @@ The following status identifiers are currently supported: - :material-alert-decagram: – `new` - :material-trash-can: – `deprecated` +### Setting the page subtitle + +[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · +[:octicons-tag-24: insiders-4.25.0][Insiders] · +:octicons-beaker-24: Experimental + +Each page can define a subtitle, which is then rendered below the title as part +of the navigation sidebar by using the front matter `subtitle` property, and +adding the following lines: + +``` yaml +--- +subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor +--- + +# Document title +... +``` + ### Setting the page template If you're using [theme extension] and created a new page template in the diff --git a/docs/schema/extensions/markdown.json b/docs/schema/extensions/markdown.json index bb2f9ddbd..271b26607 100644 --- a/docs/schema/extensions/markdown.json +++ b/docs/schema/extensions/markdown.json @@ -118,7 +118,7 @@ }, "slugify": { "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.slugify", - "type": "string" + "default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}" }, "toc_depth": { "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.toc_depth", diff --git a/docs/schema/extensions/pymdownx.json b/docs/schema/extensions/pymdownx.json index 917b7859f..c0560d83c 100644 --- a/docs/schema/extensions/pymdownx.json +++ b/docs/schema/extensions/pymdownx.json @@ -159,12 +159,10 @@ "properties": { "emoji_generator": { "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.emoji_generator", - "type": "string", "default": "!!python/name:materialx.emoji.to_svg" }, "emoji_index": { "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.emoji_index", - "type": "string", "default": "!!python/name:materialx.emoji.twemoji" }, "options": { diff --git a/docs/schema/plugins/blog.json b/docs/schema/plugins/blog.json index 530fc427c..eea2da75b 100644 --- a/docs/schema/plugins/blog.json +++ b/docs/schema/plugins/blog.json @@ -85,8 +85,7 @@ "post_slugify": { "title": "Post slugify function", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify", - "type": "string", - "default": "!!python/name:pymdownx.slugs.uslugify" + "default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}" }, "post_slugify_separator": { "title": "Post slugify separator", @@ -231,8 +230,7 @@ "categories_slugify": { "title": "Categories slugify function", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_slugify", - "type": "string", - "default": "!!python/name:pymdownx.slugs.uslugify" + "default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}" }, "categories_slugify_separator": { "title": "Categories slugify separator", diff --git a/docs/schema/plugins/tags.json b/docs/schema/plugins/tags.json index 72b89b966..a62e084fd 100644 --- a/docs/schema/plugins/tags.json +++ b/docs/schema/plugins/tags.json @@ -15,6 +15,12 @@ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#built-in-tags-plugin", "type": "object", "properties": { + "enabled": { + "title": "Enable plugin", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.enabled", + "type": "boolean", + "default": true + }, "tags_file": { "title": "Markdown file to render tags index", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_file", @@ -34,6 +40,26 @@ } }, "additionalProperties": false + }, + "tags_slugify": { + "title": "Tags slugify function", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_slugify", + "default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}" + }, + "tags_slugify_separator": { + "title": "Tags slugify separator", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_slugify_separator", + "type": "string", + "default": "\"-\"" + }, + "tags_allowed": { + "title": "Tags allowed", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_allowed", + "type": "array", + "items": { + "type": "string" + }, + "default": [] } }, "additionalProperties": false diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md index a1a3eafed..fd91ed30a 100644 --- a/docs/setup/adding-a-comment-system.md +++ b/docs/setup/adding-a-comment-system.md @@ -42,14 +42,14 @@ Before you can use [Giscus], you need to complete the following steps: ``` -The by default empty [`comments.html`][comments] partial is the best place to -add the code snippet generated by [Giscus]. Follow the guide on [theme extension] +The [`comments.html`][comments] partial (empty by default) is the best place to +add the snippet generated by [Giscus]. Follow the guide on [theme extension] and [override the `comments.html` partial][overriding partials] with: ``` html hl_lines="3" {% if page.meta.comments %}

{{ lang.t("meta.comments") }}

- +