Sidebar Configuration

Sidebar data is generated by the Sidebar Plugin, which uses page priorities and configured sort fields to order pages.

A page can add a sidebar property to its 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:

A sidebar group when expanded will reveal the pages contained within the group. Each group has a default page, index.mdx, which is the default for the group and any breadcrumb link.

Theindex.mdx can define a groupLabel which defines the name of the sidebar group. If no groupLabel is defined, sidebar group labels will be defined by either label or title.

To specify the label of the default page, refer to [Sidebar label](./Sidebar label)

---
title: Sidebar Configuration
layout: DetailTechnical
sidebar:
  groupLabel: Group 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.

---
title: Sidebar Configuration
layout: DetailTechnical
sidebar:
  label: A New Label
---

Sidebar priority is a number used to sort the sidebar. Higher the priority pages appear first in the sidebar ordering.

---
title: Sidebar Configuration
layout: DetailTechnical
sidebar:
  priority: 10
---

Excluding a page

sidebar:
  exclude: true

This hides the page from the sidebar and previous/next navigation. It does not hide child pages. An excluded index.mdx, including a namespace landing page, still defines the group's label, priority, and sort configuration. Groups with no visible descendants are omitted.

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.

Warning

Priority takes precedence over sort configuration so it can be used to override the sort configuration if required.

You must add the sidebar sort configuration to the sharedConfig.sidebar.sort property of an index page e.g.,

sharedConfig:
  sidebar:
    sort:
      field: data/title
      dataType: string
      arrange: desc

The properties of the sort configuration are described in the table below:

PropertyDescriptionRequired
fieldthe path, separated by /, used to find the value in page frontmatter you wish to sort byYes
dataTypeis the type of the value. Can be a string or number or date.Yes
arrangeasc or desc orderyes

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:

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:

---
title: Newsletter 01 Jan 2023
description: Newsletter 01 Jan 2023
data:
  title:
    $ref: '#/title'
  link: /newsletters/2023-01-01
  publicationDate: '2023-01-01'
---
Mosaic BETA

Coming soon