SidebarPlugin

The SidebarPlugin generates the necessary page metadata needed for the vertical navigation shown on some Mosaic pages.

The output from the plugin is added to a sidebarData metadata property of the page.

Configuration

The rootDirGlob is used to determine the "root" directories of the sidebar. So for example:

  • */*/* - generate sidebar data for the pages that are 3 directories deep in the filesystem hierarchy
  • */!(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 configure the sidebar using page frontmatter.

Set sidebar.exclude: true to hide a page's link without hiding its descendants. An excluded root or intermediate index.mdx still supplies the group's label, priority, and sort configuration. Empty groups are omitted, and a root whose pages are all excluded produces an empty sidebar. Previous/next navigation visits only included pages.

For a namespace-wide tree, set rootDirGlob to that namespace's directory. Components can consume the generated tree through useSidebar().menu; it does not need to be copied into sharedConfig.sidebar. Each root still needs a page directly within it to establish its structure.

Reusing the tree builder

Import buildSidebarTree from @jpmorganchase/mosaic-plugins/sidebar to reuse Mosaic's traversal with your own storage and rendering. It accepts deserialized pages and returns the root group, without writing files or adding any sidebar or previous/next references. SidebarPlugin uses this same builder.

import { buildSidebarTree, compareSidebarNodes } from '@jpmorganchase/mosaic-plugins/sidebar';

const root = buildSidebarTree(pages, {
  rootDir: '/salt',
  transformPage: (node, page) => ({
    ...node,
    metadata: { status: page.status }
  }),
  transformGroup: (node, { indexPage }) => ({
    ...node,
    priority: indexPage?.groupPriority ?? node.priority,
    metadata: { status: indexPage?.status }
  }),
  compareNodes: (a, b) => compareSidebarNodes(a, b) || a.name.localeCompare(b.name)
});

const menu = root?.childNodes ?? [];
// Persist or adapt `menu` to your site's own navigation format.

The hooks receive newly created nodes. transformPage runs for visible pages; transformGroup runs bottom-up and receives the group's original index page, including an excluded index, or undefined when there is no index. Group priorities can therefore differ from Overview-page priorities. Add badges or other data in metadata. Input pages are not changed by the builder.

compareNodes replaces sorting at every level and receives the parent group as a third argument. Use compareSidebarNodes first to preserve priority and configured field ordering, then add an alphabetical tie-break. Groups with no index retain their nested descendants. An empty non-root group is omitted. If no page sits directly within rootDir, the builder returns undefined.

Call the builder from your own plugin module if you need these callbacks during content generation. Plugin configuration is sent to worker threads, so callbacks must live in the module rather than in serialized plugin options.

Priority

This plugin runs with a priority of 3.

Options

PropertyDescription
filenamefilename of the sidebar json, linked to each related page via ref
rootDirGlobGlob pattern for matching directories which should be the root of the sidebar

Adding to Mosaic

Add the following to the plugins collection:

plugins: [
  {
    modulePath: '@jpmorganchase/mosaic-plugins/SidebarPlugin',
    options: { rootDirGlob: '*/*/*' }
  }
  // other plugins
];
Mosaic BETA

Coming soon