Content Modeling

Introduction to configuring your content models for use with Stackbit.

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

This section applies to sites using Content Source Interface. See below for information on file-based content (Git CMS).

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 getSchema 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.

  • 1
  • 2
  • 3
  • 4
  • 5
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.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
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.

Page Editor Properties
Page Editor Properties
  • 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.

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)

This property is experimental. It's currently being used to support localization. Behavior may be rapidly adjusted. Please contact us for more information and to stay updated with the latest changes.

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

Required
No.
Allowed Values
A function receiving a single argument as an object with a documents property.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
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.

Required
No.
Allowed Values
A function receiving a single argument as an object with a models property.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
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.

Required
No.
Allowed Values
An array of model objects.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
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 (deprecated)

For Git CMS, content modeling should be configured through the content source definition. Models from other sources are inferred automatically, and can be extended with the modelExtensions property.

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.

Required
Yes, for Git CMS.
Allowed Values
An object of key-value pairs, where the key is the model ID and the value is the configuration for that model.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
export default defineStackbitConfig({
  models: {
    page: {
      // page properties ...
    },
    post: {
      // post properties ...
    },
    // additional model definitions ...
  },
  // other properties ...
}