Merge branch 'master' into merge/piri-piri

CHANGELOG

@@ -1,3 +1,18 @@
+mkdocs-material-9.1.21+insiders-4.39.0 (2023-08-01)
+
+  * Added support for hoisting theme media files when building projects
+  * Added support for sorting pages on tags index for tags plugin
+  * Added support for adding date of last update to blog posts
+  * Fixed #5797: Parse error in typeset plugin (4.38.1 regression)
+
+mkdocs-material-9.1.21+insiders-4.38.1 (2023-08-01)
+
+  * Improved nested serve mode for projects plugin
+  * Improved compat in privacy plugin with third-party plugins
+  * Fixed #5790: Typeset plugin ignores data-toc-label attribute
+  * Fixed #5778: Interplay of privacy plugin with git-revision-date-localized
+  * Fixed #5773: Info plugin erroring when community edition is in beta
+
 mkdocs-material-9.1.21+insiders-4.38.0 (2023-07-29)
 
   * Added projects plugin for building nested projects

docs/getting-started.md

@@ -123,16 +123,31 @@ The following plugins are bundled with the Docker image:
 ??? question "How to add plugins to the Docker image?"
 
     Material for MkDocs only bundles selected plugins in order to keep the size
-    of the official image small. If the plugin you want to use is not included, 
-    create a `user-requirements.txt` file in the repository root with the packages
-    you want to install additionally, e.g.:
+    of the official image small. If the plugin you want to use is not included,
+    you can add them easily:
 
-    ``` txt title="user-requirements.txt"
-    mkdocs-macros-plugin==0.7.0
-    mkdocs-glightbox>=0.3.1
-    ```
+    === "Material for MkDocs" 
 
-    Next, you can build the image with the following command:
+        Create a `Dockerfile` and extend the official image:
+
+        ``` Dockerfile title="Dockerfile"
+        FROM squidfunk/mkdocs-material
+        RUN pip install mkdocs-macros-plugin
+        RUN pip install mkdocs-glightbox
+        ```
+
+    === "Insiders"
+
+        Clone or fork the Insiders repository, and create a file called
+        `user-requirements.txt` in the root of the repository. Then, add the
+        plugins that should be installed to the file, e.g.:
+
+        ``` txt title="user-requirements.txt"
+        mkdocs-macros-plugin
+        mkdocs-glightbox
+        ```
+
+    Next, build the image with the following command:
 
     ```
     docker build -t squidfunk/mkdocs-material .

docs/insiders/changelog.md

@@ -2,6 +2,21 @@
 
 ## Material for MkDocs Insiders
 
+### 4.39.0 <small>August 3, 2023</small> { id="4.39.0" }
+
+- Added support for hoisting theme media files when building projects
+- Added support for sorting pages on tags index for tags plugin
+- Added support for adding date of last update to blog posts
+- Fixed #5797: Parse error in typeset plugin (4.38.1 regression)
+
+### 4.38.1 <small>August 1, 2023</small> { id="4.38.1" }
+
+- Improved nested serve mode for projects plugin
+- Improved compat in privacy plugin with third-party plugins
+- Fixed #5790: Typeset plugin ignores data-toc-label attribute
+- Fixed #5778: Interplay of privacy plugin with git-revision-date-localized
+- Fixed #5773: Info plugin erroring when community edition is in beta
+
 ### 4.38.0 <small>July 29, 2023</small> { id="4.38.0" }
 
 - Added projects plugin for building nested projects

docs/setup/building-an-optimized-site.md

@@ -118,6 +118,28 @@ The following configuration options are available for projects:
           projects_dir: path/to/folder
     ```
 
+#### Hoisting
+
+The following configuration options are available for hoisting:
+
+[`hoisting`](#+projects.hoisting){ #+projects.hoisting }
+
+:   [:octicons-tag-24: insiders-4.39.0][Insiders] · :octicons-milestone-24:
+    Default: `true` – This option specifies whether the plugin should hoist all 
+    themes files to the top-level project. If you disable this setting, each
+    project will have a copy of the themes files, which in general, can be
+    considered redundant:
+
+    ``` yaml
+    plugins:
+      - projects:
+          hoisting: false
+    ```
+
+    It's generally advisable to enable hoisting, as it leads to faster
+    deployments and faster loading of your project's sites, because the files
+    are the same for all projects.
+
 ### Built-in optimize plugin
 
 [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·

docs/setup/setting-up-a-blog.md

@@ -978,7 +978,7 @@ Create a new file called `hello-world.md` and add the following lines:
 ``` yaml
 ---
 draft: true # (1)!
-date: 2022-01-31
+date: 2022-01-31 # (2)!
 categories:
   - Hello
   - World
@@ -993,6 +993,9 @@ categories:
     output. [This behavior can be changed], e.g. for rendering drafts when 
     building deploy previews.
 
+2.  You can use `date_updated` to signal when you updated a blog posts. The
+    date will be rendered as part of the sidebar.
+
 When you spin up the [live preview server], you should be greeted by your first
 post! You'll also realize, that [archive] and [category] indexes have been
 automatically generated for you.

docs/setup/setting-up-tags.md

@@ -159,6 +159,43 @@ The following configuration options are available:
           tags_compare_reverse: true
     ```
 
+[`tags_pages_compare`](#+tags.tags_pages_compare){ #+tags.tags_pages_compare }
+
+:   [:octicons-tag-24: insiders-4.39.0][Insiders] · :octicons-milestone-24:
+    Default: `None` – This option specifies which function to use when
+    comparing pages for sorting. If you wish to sort pages, use:
+
+    === "Sort by page title"
+
+        ``` yaml
+        plugins:
+          - tags:
+              tags_pages_compare: !!python/name:material.plugins.tags.page_title
+        ```
+
+    === "Sort by page URL"
+
+        ``` yaml
+        plugins:
+          - tags:
+              tags_pages_compare: !!python/name:material.plugins.tags.page_url
+        ```
+
+    You can also define your own comparison function which must return a page
+    value (as a string) that is used for sorting, and reference it accordingly.
+
+[`tags_pages_compare_reverse`](#+tags.tags_pages_compare_reverse){ #+tags.tags_pages_compare_reverse }
+
+:   [:octicons-tag-24: insiders-4.39.0][Insiders] · :octicons-milestone-24:
+    Default: `false` – This option specifies whether pages are sorted in reverse
+    order. It is mainly provided for completeness. To change direction, use:
+
+    ``` yaml
+    plugins:
+      - tags:
+          tags_pages_compare_reverse: true
+    ```
+
 [`tags_allowed`](#+tags.tags_allowed){ #+tags.tags_allowed }
 
 :   [:octicons-tag-24: insiders-4.25.0][Insiders] · :octicons-milestone-24: