Navigation

Stackbit provides multiple methods for viewing the structure of your site and the objects within it.

Content Editor#

Navigation within the content editor will work once a content source is configured, but can be customized with the properties below.

treeViews#

Controls the structure of the tree view in the content editor.

import {
  defineStackbitConfig,
  DocumentWithSource,
  TreeViewNode,
} from '@stackbit/types'

export default defineStackbitConfig({
  stackbitVersion: '~0.6.0',
  contentSources: [
    /* ... */
  ],
  treeViews: async ({ getDocuments }) => {
    const children: TreeViewNode['children'] = getPages(getDocuments()).map(
      (document) => ({
        document,
        label: getFieldValue(document, 'title'),
      }),
    )
    return [
      { label: 'Site Pages', children, stableId: 'pages-tree' },
    ] as TreeViewNode[]
  },
})

function getFieldValue(page: DocumentWithSource, field: string) {
  const fieldObject = page.fields[field]
  if (!fieldObject || !('value' in fieldObject)) return
  return fieldObject.value
}

function getPages(documents: DocumentWithSource[]) {
  return documents.filter((document) => document.modelName === 'Page')
}

• The top-level TreeViewNode items must contain children or they will not be rendered in the tree.

Parameters#

The function is passed a single options object of type ConfigDelegate, which contains the following properties:

• getDefaultLocaleBySource
• getDocumentById
• getDocumentFieldForFieldPath
• getDocuments
• getLogger
• getModelByName
• getSchemas

These properties can be used to retrieve the models, documents, and field values necessary to build a tree with the site content.

Return Value#

The return value should be an array of TreeViewNode objects.

When the node in the tree represents a document, the shape of the object should be:

• document: A DocumentWithSource object. If retrieving documents with options.getDocuments(), supplying the individual documents here will suffice.
• label (optional): Override the default label for the document, which is a title-like field.
• stableId (optional): A unique ID for the document. This is unnecessary with typical usage.
• children (optional): An array of nested tree view nodes.

When a node is a text-based grouping of other nodes, it supports the following properties:

• label: A string value, which will be the text shown on the screen.
• stableId: A unique ID for the node.
• children (optional): An array of nested tree view nodes.

The usage example above shows both of these node types.

Sitemap Navigator#

The sitemap navigator gets populated either from the output of the siteMap property or using the urlPath property of every document from a page type model.

siteMap#

Explicitly sets the list of pages listed in the sitemap navigator.

import { ContentfulContentSource } from '@stackbit/cms-contentful'
import {
  defineStackbitConfig,
  getLocalizedFieldForLocale,
  SiteMapEntry,
} from '@stackbit/types'

export default defineStackbitConfig({
  stackbitVersion: '~0.6.0',
  contentSources: [new ContentfulContentSource(/* ... */)],
  modelExtensions: [{ name: 'page', type: 'page', urlPath: '/{slug}' }],
  siteMap: ({ documents, models }) => {
    const pageModels = models
      .filter((m) => m.type === 'page')
      .map((m) => m.name)
    return documents
      .filter((d) => pageModels.includes(d.modelName))
      .map((document) => {
        const slug = getLocalizedFieldForLocale(document.fields.slug)
        if (!slug.value) return null
        const urlPath = '/' + slug.value.replace(/^\/+/, '')
        return {
          stableId: document.id,
          urlPath,
          document,
          isHomePage: urlPath === '/',
        }
      })
      .filter(Boolean) as SiteMapEntry[]
  },
})

• Type definitions are being explored and may change.
• Notice the following about the highlighted code above:
  • pageModels makes use of modelExtensions by automatically retrieving a set of model names when type is set to page.
  • Documents without a slug are ignored because a urlPath cannot be determined.
  • getLocalizedFieldForLocale is a utility that introspects an object and returns the appropriate field object. Within that object, a value property contains the value for the field.