Documentation

docs/insiders/changelog/index.md

@@ -2,6 +2,11 @@
 
 ## Material for MkDocs Insiders
 
+### 4.53.0 <small>February 24, 2024</small> { id="4.53.0" }
+
+- Added support for automatic instant previews
+- Added support for pinned blog posts
+
 ### 4.52.3 <small>February 21, 2024</small> { id="4.52.3" }
 
 - Fixed resolution of URLs in instant previews

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:
 
 <div class="mdx-columns" markdown>
 
-- [x] [Instant previews] :material-alert-decagram:{ .mdx-pulse title="Added on January 28, 2023" }
+- [x] [Blog plugin: pinned posts] :material-alert-decagram:{ .mdx-pulse title="Added on February 24, 2024" }
-- [x] [Footnote tooltips] :material-alert-decagram:{ .mdx-pulse title="Added on January 24, 2023" }
+- [x] [Instant previews] :material-alert-decagram:{ .mdx-pulse title="Added on January 28, 2024" }
-- [x] [Tags plugin: advanced settings] :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
+- [x] [Footnote tooltips] :material-alert-decagram:{ .mdx-pulse title="Added on January 24, 2024" }
-- [x] [Tags plugin: nested tags] :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
+- [x] [Tags plugin: advanced settings]
-- [x] [Tags plugin: shadow tags] :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
+- [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

docs/plugins/blog.md

@@ -1585,6 +1585,29 @@ draft: true
 
 ---
 
+#### <!-- md:setting meta.pin -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.53.0 -->
+<!-- md:flag metadata -->
+<!-- md:default `false` -->
+<!-- md:flag experimental -->
+
+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
+...
+```
+
+---
+
 #### <!-- md:setting meta.links -->
 
 <!-- md:sponsors -->

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
 
 <!-- md:sponsors -->
 <!-- md:version insiders-4.47.0 -->

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
 
 <!-- md:sponsors -->
 <!-- md:version insiders-4.46.0 -->
@@ -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" }
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.53.0 -->
+<!-- md:flag experimental -->
+
+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

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
+keep the user in context. Instant previews can be enabled on any internal link
-`data-preview` attribute:
+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
 
 </div>
 
+#### Automatic previews
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.53.0 -->
+<!-- md:extension -->
+<!-- md:flag experimental -->
+
+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:

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
 
 <!-- md:sponsors -->
 <!-- md:version insiders-4.48.0 -->
@@ -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