From aae0122680fcf43de261c1713d97cdba2f2e97a0 Mon Sep 17 00:00:00 2001
From: squidfunk <martin.donath@squidfunk.com>
Date: Thu, 3 Aug 2023 19:55:57 +0200
Subject: [PATCH] Documentation

---
 docs/setup/setting-up-a-blog.md |  5 ++++-
 docs/setup/setting-up-tags.md   | 37 +++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/docs/setup/setting-up-a-blog.md b/docs/setup/setting-up-a-blog.md
index 08d2db59a..c400c9dd2 100644
--- a/docs/setup/setting-up-a-blog.md
+++ b/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.
diff --git a/docs/setup/setting-up-tags.md b/docs/setup/setting-up-tags.md
index 921e5b897..0eaca3772 100644
--- a/docs/setup/setting-up-tags.md
+++ b/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: