Content Sources

Technical reference for working with one or more content sources.

New Feature

Content source configuration is a new feature. It is expected to significantly evolve further.

With the introduction of JavaScript-based configuration, Stackbit now allows for one or more content sources through the contentSources property.

The exception to this is when using files as the content source (Git CMS). Configuring a file-based content source is currently using legacy properties that will soon be deprecated.

Shared Properties

While we're in the process of transitioning files source to use the contentSources property, the modelsproperty is the only that applies to all content sources.

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

API CMS

API-based content sources are configured using a combination of the contentSources and models properties.

contentSources

Define one or more content sources that your project is using.

Required
Yes, if using API CMS.
Allowed Values
An array of JavaScript classes. See below for details.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
import { ContentfulContentSource } from '@stackbit/cms-contentful'

export default {
  contentSources: [
    new ContentfulContentSource({
      spaceId: process.env.CONTENTFUL_SPACE_ID,
      environment: process.env.CONTENTFUL_ENVIRONMENT,
      previewToken: process.env.CONTENTFUL_PREVIEW_TOKEN,
      accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN,
    }),
  ],
  models: {
    // page definitions and model decorations ...
  },
  // other properties ...
}
  • Each content source has its own module with a unique set of properties. See the following integration guides for more information about working with that source:
  • For most sources, this property must be paired with the models property to tell Stackbit which models represent your pages.
    • See Content Modeling for the technical reference.
    • The integration guide (listed above) will also have a relevant example in working with the models property.

Git CMS (Files Source)

Using files as a content source will soon be handled similarly to API CMS (above). In the interim, these properties apply only when storing your content in files alongside the code.

assets

Tells Stackbit where to store and retrieve media files for projects using files as the content source.

Required
Yes, if using Git CMS.
Allowed Values

cmsName

Tells Stackbit to use files as the content source.

Required
Yes, if using Git CMS.
Allowed Values
git
  • 1
  • 2
  • 3
  • 4
export default {
  cmsName: 'git',
  // other properties ...
}
  • This is deprecated for all values other than git. Projects using API CMS(s) should use the contentSources property.

dataDir

The directory containing non-page data. These are typically values that are used globally across your project, like site title and URL, or SEO defaults.

Required
Yes, if using Git CMS.
Allowed Values
A string specifying the directory path, relative to the root of the project.
  • 1
  • 2
  • 3
  • 4
  • 5
export default {
  cmsName: 'git',
  dataDir: 'content/data',
  // other properties ...
}

excludePages

Excludes files in your pagesDir that should not be treated as pages.

Required
No
Allowed Values
An array of file paths or glob patterns (as strings), relative to the pagesDir directory.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
export default {
  cmsName: 'git',
  pagesDir: 'content',
  excludePages: ['internal/**/*', 'README.md'],
  // other properties ...
}

modelsSource

Tells Stackbit where to look for YAML files that define individual models. This is typically not needed, but can be used to load models from external packages or third-party libraries.

Required
No
Allowed Values

An object containing two properties:

  • type: Set to files
  • modelDirs: An array of directory paths, relative to the root of the project.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
export default {
  cmsName: 'git',
  modelsSource: {
    type: 'files',
    modelDirs: ['stackbit/models'],
  },
  // other properties ...
}
  • This is deprecated for API CMSs, which should use the contentSources property.
  • If cmsName is set to git, Stackbit automatically looks in .stackbit/models for YAML model definitions.
  • Directories should be listed from lower to higher priority. If Stackbit finds conflicting models, it will use the one defined last in the array of directories.
  • Model files must have a .yaml or .yml file extension and the directory must exist, or the Stackbit visual editor may not work properly.

objectTypeKey

Defines the field name used to identify the type of objects referenced by model or reference fields.

Required
No
Allowed Values
A string representing the field key to use for stored model or reference values.
Default
type
  • 1
  • 2
  • 3
  • 4
  • 5
export default {
  cmsName: 'git',
  objectTypeKey: 'model',
  // other properties ...
}

pageLayoutKey

Defines the field name used to match pages to the appropriate page model.

Required
No
Allowed Values
A string representing the field key to use for store the page model on a page file.
Default
layout
  • 1
  • 2
  • 3
  • 4
  • 5
export default {
  cmsName: 'git',
  pageLayoutKey: 'layout',
  // other properties ...
}

pagesDir

The directory containing page content.

Required
Yes, if using Git CMS.
Allowed Values
A string specifying the directory path, relative to the root of the project.
  • 1
  • 2
  • 3
  • 4
  • 5
export default {
  cmsName: 'git',
  pagesDir: 'content/pages',
  // other properties ...
}