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.

API CMS

Paid Feature

Using API CMSs as your content source is a paid feature.

If your project is using a supported API-based CMS, the content model is automatically inferred from the CMS and there's no need to define it explicitly.

Your project will likely still use Stackbit's content modeling configuration to do the following:

  • Inform Stackbit which models represent the pages of your site. This enables the sitemap navigator and page editor.
  • Decorate your model fields by adding control types to specify how those fields should appear within Stackbit. (Field control types are inferred as best as possible.)

Defining Pages

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
  • 6
  • 7
  • 8
  • 9
export default {
  models: {
    page: {
      type: 'page',
      urlPath: '/{slug}',
    },
  },
  // other properties ...
}

Decorating Fields

In some cases, you may want to customize the control type of the field as it appears 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
export default {
  models: {
    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 ...
}

Git CMS (File-Based Content)

Projects that store content in files within the repository must fully define the content schema for the site. See below for properties within the models config.

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.

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.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
import page from '.stackbit/models/page'

export default {
  models: { page },
  // other properties ...
}

Legacy YAML Configuration

YAML Config Deprecated

Using the legacy YAML configuration is deprecated and may be removed in a future version of Stackbit. Please consider updating to JavaScript 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.

models

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, although some content sources may not require it.
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 {
  models: {
    page: {
      // page properties ...
    },
    post: {
      // post properties ...
    },
    // additional model definitions ...
  },
  // other properties ...
}