From f26cfaaa58ede5c09de9c6b633a113e2fdc74e68 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sat, 24 Feb 2024 12:46:13 +0700 Subject: [PATCH] Documentation --- docs/insiders/changelog/index.md | 5 +++ docs/insiders/index.md | 15 +++++--- docs/plugins/blog.md | 23 ++++++++++++ docs/setup/changing-the-language.md | 2 +- docs/setup/setting-up-a-blog.md | 25 ++++++++++++- docs/setup/setting-up-navigation.md | 57 ++++++++++++++++++++++++++++- docs/setup/setting-up-tags.md | 4 +- 7 files changed, 119 insertions(+), 12 deletions(-) diff --git a/docs/insiders/changelog/index.md b/docs/insiders/changelog/index.md index 57e89330212..e220b526cf4 100644 --- a/docs/insiders/changelog/index.md +++ b/docs/insiders/changelog/index.md @@ -2,6 +2,11 @@ ## Material for MkDocs Insiders +### 4.53.0 February 24, 2024 { id="4.53.0" } + +- Added support for automatic instant previews +- Added support for pinned blog posts + ### 4.52.3 February 21, 2024 { id="4.52.3" } - Fixed resolution of URLs in instant previews diff --git a/docs/insiders/index.md b/docs/insiders/index.md index b1e76df9bf9..584e6565a8d 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -88,16 +88,17 @@ 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 25 additional features__ that you can __start using now__, and +access to 26 additional features__ that you can __start using now__, and which are currently exclusively available to sponsors:
-- [x] [Instant previews] :material-alert-decagram:{ .mdx-pulse title="Added on January 28, 2023" } -- [x] [Footnote tooltips] :material-alert-decagram:{ .mdx-pulse title="Added on January 24, 2023" } -- [x] [Tags plugin: advanced settings] :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" } -- [x] [Tags plugin: nested tags] :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" } -- [x] [Tags plugin: shadow tags] :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" } +- [x] [Blog plugin: pinned posts] :material-alert-decagram:{ .mdx-pulse title="Added on February 24, 2024" } +- [x] [Instant previews] :material-alert-decagram:{ .mdx-pulse title="Added on January 28, 2024" } +- [x] [Footnote tooltips] :material-alert-decagram:{ .mdx-pulse title="Added on January 24, 2024" } +- [x] [Tags plugin: advanced settings] +- [x] [Tags plugin: nested tags] +- [x] [Tags plugin: shadow tags] - [x] [Stay on page when switching languages] - [x] [Blog plugin: author profiles] - [x] [Blog plugin: advanced settings] @@ -303,6 +304,7 @@ are released for general availability. - [x] [Instant prefetching] - [x] [Blog plugin: advanced settings] - [x] [Blog plugin: author profiles] +- [x] [Blog plugin: pinned posts] - [x] [Footnote tooltips] [Optimize plugin]: ../plugins/optimize.md @@ -313,6 +315,7 @@ are released for general availability. [Instant prefetching]: ../setup/setting-up-navigation.md#instant-prefetching [Blog plugin: advanced settings]: ../setup/setting-up-a-blog.md#advanced-settings [Blog plugin: author profiles]: ../setup/setting-up-a-blog.md#adding-author-profiles + [Blog plugin: pinned posts]: ../setup/setting-up-a-blog.md#pinning-a-post [Footnote tooltips]: ../reference/footnotes.md#footnote-tooltips #### $ 24,000 – Blockpaprika diff --git a/docs/plugins/blog.md b/docs/plugins/blog.md index 7ef827f45c1..503fd7af498 100644 --- a/docs/plugins/blog.md +++ b/docs/plugins/blog.md @@ -1585,6 +1585,29 @@ draft: true --- +#### + + + + + + + +Use this property to pin a post to the top of a view. In case multiple posts are +pinned, the pinned posts are sorted by descending order and appear before all +other posts. Pin a post with: + +``` yaml +--- +ping: true +--- + +# Post title +... +``` + +--- + #### diff --git a/docs/setup/changing-the-language.md b/docs/setup/changing-the-language.md index 1519206e200..164f27a0cf6 100644 --- a/docs/setup/changing-the-language.md +++ b/docs/setup/changing-the-language.md @@ -97,7 +97,7 @@ The following properties are available for each alternate language: [ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes [Language selector preview]: ../assets/screenshots/language-selection.png -#### Stay on page :material-alert-decagram:{ .mdx-pulse title="Added on December 8, 2023" } +#### Stay on page diff --git a/docs/setup/setting-up-a-blog.md b/docs/setup/setting-up-a-blog.md index 83b2642d15d..769bcbeb015 100644 --- a/docs/setup/setting-up-a-blog.md +++ b/docs/setup/setting-up-a-blog.md @@ -342,7 +342,7 @@ authors: [authors]: ../plugins/blog.md#authors [authors_file]: ../plugins/blog.md#config.authors_file -#### Adding author profiles :material-alert-decagram:{ .mdx-pulse title="Added on November 26, 2023" } +#### Adding author profiles @@ -506,6 +506,29 @@ when the site is being built. Of course, you can also reference assets from posts outside of the `posts` directory. The [built-in blog plugin] ensures that all links are correct. +#### Pinning a post :material-alert-decagram:{ .mdx-pulse title="Added on February 24, 2024" } + + + + + +If you want to pin a post to the top of the index page, as well as the archive +and category indexes it is part of, you can use the front matter `pin` property: + +``` yaml +--- +date: 2024-01-31 +pin: true +--- + +# Hello world! +... +``` + +If multiple posts are pinned, they are sorted by their creation date, with the +most recent pinned post being shown first, followed by the other pinned posts in +descending order. + #### Setting the reading time When [enabled], the [readtime] package is used to compute the expected reading diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md index bce44b51657..4ee9389e6b3 100644 --- a/docs/setup/setting-up-navigation.md +++ b/docs/setup/setting-up-navigation.md @@ -93,8 +93,8 @@ experience. Instant previews are a brand new feature that allow the user to preview another site of your documentation without navigating to it. They can be very helpful to -keep the user in context. A link can be opted into instant previews with the -`data-preview` attribute: +keep the user in context. Instant previews can be enabled on any internal link +with the `data-preview` attribute: ```` markdown title="Link with instant preview" ``` markdown @@ -108,6 +108,59 @@ keep the user in context. A link can be opted into instant previews with the
+#### Automatic previews + + + + + + +The recommended way to work with instant previews is to use the Markdown +extension that is included with Material for MkDocs, as it allows you to enable +instant previews on a per-page or per-section level for your documentation: + +``` yaml +markdown_extensions: + - material.extensions.preview: + targets: + include: + - changelog/index.md + - customization.md + - insiders/changelog/* + - setup/extensions/* +``` + +The above configuration is what we use for our documentation. We've enabled +instant previews for our changelogs, customization guide, and Insiders sections, +as well as for all Markdown extensions that we support. + +!!! info "Full configuration example" + + ``` yaml + markdown_extensions: + - material.extensions.preview: + sources: # (1)! + include: + - ... + exclude: + - ... + targets: # (2)! + include: + - ... + exclude: + - ... + ``` + + 1. Sources specify the pages _on_ which instant previews should be enabled. + If this setting is omitted, instant previews will be enabled on all + pages. You can use patterns to include or exclude pages. Exclusion is + evaluated on top of inclusion, so if a page is matched by both, it will + be excluded. + + 2. Targets specify the pages _to_ which instant previews should be enabled. + This is the recommended way to enable instant previews. +--- + Instant previews can also be enabled globally by adding the following lines to `mkdocs.yml`, which will enable instant previews for all internal links, alleviating the need to add data attributes: diff --git a/docs/setup/setting-up-tags.md b/docs/setup/setting-up-tags.md index 0b79eff5ba3..644ea45e667 100644 --- a/docs/setup/setting-up-tags.md +++ b/docs/setup/setting-up-tags.md @@ -27,7 +27,7 @@ For a list of all settings, please consult the [plugin documentation]. [plugin documentation]: ../plugins/tags.md -#### Advanced settings :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" } +#### Advanced settings @@ -211,7 +211,7 @@ arbitrary content before and after the marker: [tags.tags_file]: #tags-file [tags index enabled]: ../assets/screenshots/tags-index.png -### Advanced features :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" } +### Advanced features [Insiders] ships a __ground up rewrite of the tags plugin__ which is infinitely more powerful than the current version in the community edition. It allows