Sidebar sort config docs

docs/author/markdown-syntax.mdx

@@ -22,7 +22,7 @@ This includes components for all standard markdown syntax and additional compone
 
 ## Referencing Frontmatter
 
-Frontmatter values into the page using the `meta` object. See [frontmatter](./frontmatter#accessing-frontmatter-in-content) for more information.
+Frontmatter values can be embedded into the page using the `meta` object. See [frontmatter](./frontmatter#accessing-frontmatter-in-content) for more information.
 
 ## Configuring Supported components
 

docs/author/sidebars.mdx

@@ -0,0 +1,99 @@
+---
+title: Sidebar Configuration
+layout: DetailTechnical
+---
+
+# {meta.title}
+
+Sidebar data is generated by the the [Sidebar Plugin](../configure/plugins/sidebar-plugin) which by default uses alphabetical ordering of page names to order the sidebar.
+
+## Sidebar frontmatter
+
+A page can add a `sidebar` property to its [frontmatter](./frontmatter) to change the ordering of a sidebar and what title is used for a page in the sidebar.
+
+To rearrange pages in the sidebar or to apply a different label to a page you can specify the following in the page frontmatter:
+
+### Sidebar label
+
+By default the _title_ of a page is used in the sidebar as the label but this can be changed to another label using page frontmatter.
+
+```yaml
+---
+title: Sidebar Configuration
+layout: DetailTechnical
+sidebar:
+  label: A New Label
+---
+```
+
+### Sidebar priority
+
+Sidebar priority is a number used to sort the sidebar. Higher the priority pages appear first in the sidebar ordering.
+
+```yaml
+---
+title: Sidebar Configuration
+layout: DetailTechnical
+sidebar:
+  priority: 10
+---
+```
+
+## Sidebar Sort Configuration
+
+Sidebar sort configuration allows the sidebar to be sorted using a more sophisticated approach and only needs to be applied to the `index` page of the directory you want to sort.
+
+<Callout variant="warning">
+  Priority takes precedence over sort configuration so it can be used to override the sort
+  configuration if required.
+</Callout>
+
+You must add the sidebar sort configuration to the `sharedConfig.sidebar.sort` property of an **index** page e.g.,
+
+```yaml
+sharedConfig:
+  sidebar:
+    sort:
+      field: data/title
+      dataType: string
+      arrange: desc
+```
+
+The properties of the sort configuration are described in the table below:
+
+| Property | Description                                                                                | Required |
+| -------- | ------------------------------------------------------------------------------------------ | -------- |
+| field    | the path, separated by `/`, used to find the value in page frontmatter you wish to sort by | Yes      |
+| dataType | is the type of the value. Can be a `string` or `number` or `date`.                         | Yes      |
+| arrange  | `asc` or `desc` order                                                                      | yes      |
+
+### Newsletters Example
+
+Let's say you have a _Newsletters_ directory and each page in the directory represents a newsletter. You wish to sort the newsletter sidebar by publication date in descending order (newest first).
+
+One way to do this is to edit each page and add a `priority` which is manually incremented every time a news newsletter is added. Alternatively you can add the following sort configuration to the newsletters index page:
+
+```yaml
+sharedConfig:
+  sidebar:
+    sort:
+      field: data/publicationDate
+      dataType: date
+      arrange: desc
+```
+
+This will use the `data.publicationDate` property in each newsletter to sort the newsletters in the sidebar. The publication date is converted to a `date` by the Sidebar Plugin to ensure accurate ordering. There is now no need to increment a priority when a new newsletter is added.
+
+#### Example newsletter page frontmatter:
+
+```yaml
+---
+title: Newsletter 01 Jan 2023
+description: Newsletter 01 Jan 2023
+data:
+  title:
+    $ref: '#/title'
+  link: /newsletters/2023-01-01
+  publicationDate: '2023-01-01'
+---
+```

docs/configure/plugins/sidebar-plugin.mdx

@@ -17,12 +17,7 @@ The `rootDirGlob` is used to determine the "root" directories of the sidebar. So
 - `*/!(product-a)/*` - same as above but ignore the product-a directory
 - `products/product-b` - generate a sidebar just for product-b in the products directory
 
-To rearrange pages in the sidebar or to apply a different label to a page you can specify the following in the page frontmatter:
-
-| Property         | Description                                                                               |
-| ---------------- | ----------------------------------------------------------------------------------------- |
-| sidebar.label    | the name of the page to use in the sidebar. Defaults to the page title                    |
-| sidebar.priority | pages are ordered in the sidebar by priority high → low. Default is alphabetical ordering |
+To rearrange pages in the sidebar or to apply a different label to a page you can [configure the sidebar](../../author/sidebars) using page frontmatter.
 
 ## Priority
 

packages/site/snapshots/latest/mosaic/author/aliases.mdx

@@ -111,13 +111,12 @@ sidebarData:
       level: 2
       link: /mosaic/author/ui-components
     childNodes: []
-  - id: /mosaic/author/page-templates
-    fullPath: /mosaic/author/page-templates.mdx
-    name: Page Templates
-    priority: 1
+  - id: /mosaic/author/sidebars
+    fullPath: /mosaic/author/sidebars.mdx
+    name: Sidebar Configuration
     data:
       level: 2
-      link: /mosaic/author/page-templates
+      link: /mosaic/author/sidebars
     childNodes: []
 ---
 # {meta.title}

packages/site/snapshots/latest/mosaic/author/fragments.mdx

@@ -98,13 +98,12 @@ sidebarData:
       level: 2
       link: /mosaic/author/ui-components
     childNodes: []
-  - id: /mosaic/author/page-templates
-    fullPath: /mosaic/author/page-templates.mdx
-    name: Page Templates
-    priority: 1
+  - id: /mosaic/author/sidebars
+    fullPath: /mosaic/author/sidebars.mdx
+    name: Sidebar Configuration
     data:
       level: 2
-      link: /mosaic/author/page-templates
+      link: /mosaic/author/sidebars
     childNodes: []
 ---
 # {meta.title}

packages/site/snapshots/latest/mosaic/author/frontmatter.mdx

@@ -101,13 +101,12 @@ sidebarData:
       level: 2
       link: /mosaic/author/ui-components
     childNodes: []
-  - id: /mosaic/author/page-templates
-    fullPath: /mosaic/author/page-templates.mdx
-    name: Page Templates
-    priority: 1
+  - id: /mosaic/author/sidebars
+    fullPath: /mosaic/author/sidebars.mdx
+    name: Sidebar Configuration
     data:
       level: 2
-      link: /mosaic/author/page-templates
+      link: /mosaic/author/sidebars
     childNodes: []
 ---
 # {meta.title}

packages/site/snapshots/latest/mosaic/author/index.mdx

@@ -5,7 +5,7 @@ sidebar:
   priority: 3
 data:
   exampleRefData: Hello from Author page
-lastModified: 1692870573465
+lastModified: 1699619764642
 fullPath: /mosaic/author/index.mdx
 route: /mosaic/author/index
 breadcrumbs:
@@ -82,13 +82,12 @@ sidebarData:
       level: 2
       link: /mosaic/author/ui-components
     childNodes: []
-  - id: /mosaic/author/page-templates
-    fullPath: /mosaic/author/page-templates.mdx
-    name: Page Templates
-    priority: 1
+  - id: /mosaic/author/sidebars
+    fullPath: /mosaic/author/sidebars.mdx
+    name: Sidebar Configuration
     data:
       level: 2
-      link: /mosaic/author/page-templates
+      link: /mosaic/author/sidebars
     childNodes: []
 ---
 # {meta.title}

packages/site/snapshots/latest/mosaic/author/markdown-syntax.mdx

@@ -3,7 +3,7 @@ title: Markdown Syntax
 layout: DetailTechnical
 sidebar:
   priority: 5
-lastModified: 1692689032572
+lastModified: 1699608656205
 fullPath: /mosaic/author/markdown-syntax.mdx
 route: /mosaic/author/markdown-syntax
 breadcrumbs:
@@ -18,9 +18,9 @@ breadcrumbs:
     id: /mosaic/author/markdown-syntax.mdx
 readingTime:
   text: 1 min read
-  minutes: 0.505
-  time: 30300
-  words: 101
+  minutes: 0.52
+  time: 31200
+  words: 104
 tableOfContents:
   - level: 2
     id: mosaic-standard-components
@@ -92,13 +92,12 @@ sidebarData:
       level: 2
       link: /mosaic/author/ui-components
     childNodes: []
-  - id: /mosaic/author/page-templates
-    fullPath: /mosaic/author/page-templates.mdx
-    name: Page Templates
-    priority: 1
+  - id: /mosaic/author/sidebars
+    fullPath: /mosaic/author/sidebars.mdx
+    name: Sidebar Configuration
     data:
       level: 2
-      link: /mosaic/author/page-templates
+      link: /mosaic/author/sidebars
     childNodes: []
 ---
 # {meta.title}
@@ -118,7 +117,7 @@ This includes components for all standard markdown syntax and additional compone
 
 ## Referencing Frontmatter
 
-Frontmatter values into the page using the `meta` object. See [frontmatter](./frontmatter#accessing-frontmatter-in-content) for more information.
+Frontmatter values can be embedded into the page using the `meta` object. See [frontmatter](./frontmatter#accessing-frontmatter-in-content) for more information.
 
 ## Configuring Supported components
 

packages/site/snapshots/latest/mosaic/author/refs.mdx

@@ -10,7 +10,7 @@ data:
     - snapshot-file
     - snapshot-s3
   sidebarPriority: 3
-lastModified: 1692689032572
+lastModified: 1699542715973
 fullPath: /mosaic/author/refs.mdx
 route: /mosaic/author/refs
 breadcrumbs:
@@ -120,13 +120,12 @@ sidebarData:
       level: 2
       link: /mosaic/author/ui-components
     childNodes: []
-  - id: /mosaic/author/page-templates
-    fullPath: /mosaic/author/page-templates.mdx
-    name: Page Templates
-    priority: 1
+  - id: /mosaic/author/sidebars
+    fullPath: /mosaic/author/sidebars.mdx
+    name: Sidebar Configuration
     data:
       level: 2
-      link: /mosaic/author/page-templates
+      link: /mosaic/author/sidebars
     childNodes: []
 ---
 # {meta.title}

packages/site/snapshots/latest/mosaic/author/sidebar.json

@@ -1 +1 @@
-{"pages":[{"id":"/mosaic/author/index","fullPath":"/mosaic/author/index.mdx","name":"Author","priority":3,"data":{"level":2,"link":"/mosaic/author/index"},"childNodes":[]},{"id":"/mosaic/author/markdown-syntax","fullPath":"/mosaic/author/markdown-syntax.mdx","name":"Markdown Syntax","priority":5,"data":{"level":2,"link":"/mosaic/author/markdown-syntax"},"childNodes":[]},{"id":"/mosaic/author/frontmatter","fullPath":"/mosaic/author/frontmatter.mdx","name":"Frontmatter","priority":4,"data":{"level":2,"link":"/mosaic/author/frontmatter"},"childNodes":[]},{"id":"/mosaic/author/aliases","fullPath":"/mosaic/author/aliases.mdx","name":"Aliases","priority":3,"data":{"level":2,"link":"/mosaic/author/aliases"},"childNodes":[]},{"id":"/mosaic/author/refs","fullPath":"/mosaic/author/refs.mdx","name":"Refs","priority":3,"data":{"level":2,"link":"/mosaic/author/refs"},"childNodes":[]},{"id":"/mosaic/author/fragments","fullPath":"/mosaic/author/fragments.mdx","name":"Fragments","priority":2,"data":{"level":2,"link":"/mosaic/author/fragments"},"childNodes":[]},{"id":"/mosaic/author/ui-components","fullPath":"/mosaic/author/ui-components.mdx","name":"UI Components","priority":2,"data":{"level":2,"link":"/mosaic/author/ui-components"},"childNodes":[]},{"id":"/mosaic/author/page-templates","fullPath":"/mosaic/author/page-templates.mdx","name":"Page Templates","priority":1,"data":{"level":2,"link":"/mosaic/author/page-templates"},"childNodes":[]}]}
+{"pages":[{"id":"/mosaic/author/index","fullPath":"/mosaic/author/index.mdx","name":"Author","priority":3,"data":{"level":2,"link":"/mosaic/author/index"},"childNodes":[]},{"id":"/mosaic/author/markdown-syntax","fullPath":"/mosaic/author/markdown-syntax.mdx","name":"Markdown Syntax","priority":5,"data":{"level":2,"link":"/mosaic/author/markdown-syntax"},"childNodes":[]},{"id":"/mosaic/author/frontmatter","fullPath":"/mosaic/author/frontmatter.mdx","name":"Frontmatter","priority":4,"data":{"level":2,"link":"/mosaic/author/frontmatter"},"childNodes":[]},{"id":"/mosaic/author/aliases","fullPath":"/mosaic/author/aliases.mdx","name":"Aliases","priority":3,"data":{"level":2,"link":"/mosaic/author/aliases"},"childNodes":[]},{"id":"/mosaic/author/refs","fullPath":"/mosaic/author/refs.mdx","name":"Refs","priority":3,"data":{"level":2,"link":"/mosaic/author/refs"},"childNodes":[]},{"id":"/mosaic/author/fragments","fullPath":"/mosaic/author/fragments.mdx","name":"Fragments","priority":2,"data":{"level":2,"link":"/mosaic/author/fragments"},"childNodes":[]},{"id":"/mosaic/author/ui-components","fullPath":"/mosaic/author/ui-components.mdx","name":"UI Components","priority":2,"data":{"level":2,"link":"/mosaic/author/ui-components"},"childNodes":[]},{"id":"/mosaic/author/sidebars","fullPath":"/mosaic/author/sidebars.mdx","name":"Sidebar Configuration","data":{"level":2,"link":"/mosaic/author/sidebars"},"childNodes":[]}]}

packages/site/snapshots/latest/mosaic/author/sidebars

@@ -0,0 +1 @@
+sidebars.mdx