Navigation

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

Navigation Properties#

The following properties control navigation visibility and behavior.

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.

transformSitemap#

Transform the sitemap to affect the visible pages in the sitemap navigator, based on the current user context.

export default {
  transformSitemap({ sitemap, userContext }) {
    return sitemap
      .filter((sitemap) => {
        // Filtering logic based on current user context ...
      })
      .map((sitemap) => {
        // Transforming logic based on current user context ...
      })
  },
}

• The function should return an array of SiteMapEntry objects. Entries not returned from this function will not be shown in the sitemap navigator.
• filterModel and filterDocument are run before transformSitemap. Filtered out documents will have already been removed from the sitemap.

transformTreeViews#

Transforms the tree view to affect the documents and folders a user sees in the content editor tree view, based on the current user context.

export default {
  transformTreeViews({ treeViews, userContext }) {
    return treeViews
      .filter((treeView) => {
        // Filtering logic based on current user context ...
      })
      .map((treeView) => {
        // Transforming logic based on current user context ...
      })
  },
}

• The function should return an array of TreeViewNode objects. Nodes not returned from this function will not be shown in the tree views.
• transformTreeViews is called before filterModel and filterDocument are run and may contain nodes connected to documents that are filtered out. These nodes get cleaned up after filterModel and filterDocument have run and will be hidden appropriately.

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.