Content Modeling

Content modeling is the backbone of all Stackbit features, as Stackbit is designed to make it easy for your content editors to edit content from one or more sources. Learn more about how Stackbit works with structured content.

How Content is Loaded#

Stackbit automatically infers the content schema from your content sources. While the schema can be used directly, you'll often want to extend the schema for tighter control over editing behavior. More on extending content models below.

Here's how Stackbit determines the schema based on various configuration properties:

1. All models all loaded from all contentSources by calling getModels within every content source module.
2. Extend models loaded from contentSources with models loaded from modelExtensions.
3. Call mapModels() with the extended content source models (the result of the previous step). Models passed to mapModels function will always include srcType and srcProjectId properties.

The models resulting form this process are those that will be used by Stackbit.

Handling Naming Conflicts#

If a model name in modelExtensions matches more than one model with the same name from different content sources, the extension will be ignored and a warning message will be printed to console.

To resolve the issue, provide srcType or/and srcProjectId to match between models in modelExtensions with content source models.

Extending Content Models#

Models are often ended to provide additional properties that to improve the Stackbit editing experience.

There are two properties that can be used to extend models: modelExtensions and mapModels. More on these below.

Specifying Page Models#

In some cases, you know exactly which model to override and the set of properties you want to add to it.

A common case for this is specifying your page type models, which enables the sitemap navigator and the page editor panel.

Here's a simple example that specifies the CMS has a model with ID of page that specifies the pages for the site.

export default defineStackbitConfig({
  contentSources: [ /* ... */ ]
  modelExtensions: [{ name: 'page', type: 'page', urlPath: '/{slug}' }],
  // other properties ...
})

Extending Field Editor Controls#

You may also want to customize the control type of a field in Stackbit's visual editor. For these cases, you can simply override only the fields that you want to customize. Stackbit will still bring in the remaining fields for the model and assume the appropriate control type based on the CMS schema.

Here's an example that adds a button group control to a field with a limited set of options.

export default defineStackbitConfig({
  contentSources: [ /* ... */ ]
  modelExtensions: {
    {
      name: 'hero_section',
      fields: [
        {
          type: 'enum',
          name: 'width',
          label: 'Width',
          group: 'design',
          controlType: 'button-group',
          options: [
            { label: 'Narrow', value: 'narrow' },
            { label: 'Wide', value: 'wide' },
            { label: 'Full', value: 'full' },
          ],
        },
      ],
    },
  },
  // other properties ...
})

Page Editor Controls#

The properties you set on models and fields control how fields are rendered in Stackbit's page editor panel. Here's a look at several properties that determine how controls and elements are rendered in the editor.

• Model properties:
  • fieldGroups: Used to collect fields for easier editing.
  • fields: The individual fields, for which controls are determined by types and other properties on the field.
  • label: Subtext under an object's title to show the type of object being edited.
  • labelField: The value of this field is used for the main heading when editing the object.
• Field properties:
  • description: Descriptive or help text for the individual field.
  • label: Input label for the individual field.

Git (File-Based) CMS#

Git CMS is not currently supported by Content Source Interface. There are a number of properties necessary for configuring the content source.

Because this content is loosely structured by default, Stackbit requires that you define the schema for your local files. This is typically done through the models property, which will become deprecated once Git CMS becomes supported via Content Source Interface.

Model Source Files#

With JavaScript configuration, you are free to place model files in any location you'd prefer, or even define them directly in the configuration file.

The most common pattern is defining a single model per file and importing those models into the primary configuration file.

import { Page } from '.stackbit/models/page'

export default defineStackbitConfig({
  models: { page: Page },
  // other properties ...
})

Legacy YAML Configuration#

If still using the legacy YAML configuration, note that models can either be defined in the models property of stackbit.yaml or as separate files in the the .stackbit/models directory.

This behavior can be customized using the modelsSource property, including loading models from external packages.

Content Modeling Properties#

Content modeling is achieved through the models property, listed below. For more information about setting up content sources, see the content sources reference.

mapDocuments (experimental)#

A function that can be used to extend or manipulate documents that Stackbit retrieves from the content source.

export default {
  mapDocuments({ documents }) {
    return documents.map((document) => {
      return {
        ...document,
        // Add or adjust document properties ...
      }
    })
  },
}

• This can only be used when the source was defined using contentSources.
• The function should return an array of documents. Documents not returned from this function will be ignored by Stackbit.

mapModels#

A function that can be used extend schemas or other model configuration.

export default {
  mapModels({ models }) {
    return models.map((model) => {
      return {
        ...model,
        // Add or adjust model properties ...
      }
    })
  },
}

• This is an alternative to modelExtensions and can only be used when the source was defined using contentSources.
• The function should return an array of model definitions. Models not returned from this function will be ignored by Stackbit.

modelExtensions#

An array of objects used to add extend properties for a model from a content source.

export default defineStackbitConfig({
  contentSources: [
    new ContentfulContentSource({
      spaceId: process.env.CONTENTFUL_SPACE_ID!,
      environment: process.env.CONTENTFUL_ENVIRONMENT || 'master',
      previewToken: process.env.CONTENTFUL_PREVIEW_TOKEN!,
      accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN!,
    }),
  ],
  modelExtensions: [{ name: 'page', type: 'page', urlPath: '/{slug}' }],
})

• This can only be used when the source was defined using contentSources.
• When there are no naming conflicts, models can be identified using the name property.
• When multiple models from different content sources have the same name, use srcType and srcProjectId to help identify the proper model.

models (legacy)#

The models property defines the structure of your content when using files as your content source. For API CMSs, this property provides useful overrides and decorations to your remote schema.

export default defineStackbitConfig({
  models: {
    page: {
      // page properties ...
    },
    post: {
      // post properties ...
    },
    // additional model definitions ...
  },
  // other properties ...
}