Note:

This document specifics the format of stackbit.yaml version 0.4.0 or later
(see property stackbitVersion below).

To upgrade from earlier versions, see the upgrade guide.

Introduction

stackbit.yaml is a configuration file that is required for our visual editor and our default managed hosting to function correctly. It should always be located at the root of your repository.

Here is what's defined by this file:

  1. Which framework is used to run the project (e.g. Next.js), plus optional properties for customizing the commands and directories used for running the project in the visual editor and build it for production.
  2. Which models should the visual editor allow to instantiate, either as pages or as standalone content pieces. For each of these models, where to store new content files and the URL mapping of content. See contentModels.
  3. On premium plans, connecting an external headless CMS rather than the built-in Git-based CMS.

Note: you are free to build and run your website anywhere. This file is not needed for building your website for production.

Example

Here is an example of a stackbit.yaml file, adopted from our base themes.

stackbitVersion: ~0.4.0
ssgName: nextjs
nodeVersion: '14'
cmsName: git
publishDir: out
dataDir: content/data
pagesDir: content/pages
pageLayoutKey: layout
assets:
  referenceType: static
  staticDir: public
  uploadDir: images
  publicPath: /
contentModels:
  PageLayout:
    isPage: true
    urlPath: '/{slug}'
    newFilePath: '{slug}.md'
  PostLayout:
    isPage: true
    urlPath: '/blog/{slug}'
    newFilePath: 'posts/{slug}.md'
  Person:
    newFilePath: 'team/{slug}.json'

Properties

stackbitVersion

  • Allowed values: A valid version number in semver syntax. The current version is 0.4.0 and prior versions are being deprecated (link to upgrade guide).
  • Required: Yes

We recommend using the latest version with a tilde: ~0.4.0, which will use the latest applicable major version that is backwards-compatible with 0.4.0

ssgName

  • Allowed valuesnextjs, gatsby
  • Required: Yes

The name of the site generator framework used in your project. In our themes we use Next.js.

Note that Gatsby is officially supported only in our premium plans. To inquire about support for any other framework, talk to us.

cmsName

  • Allowed valuesgitcontentful
  • Required: No
  • Defaultgit

The name of the CMS your project is configured to work with. If your project uses our built-in mechanism for storing content in your Git repository, you don't need to specify this property.

Note: Contentful is officially supported only in our premium plans. To inquire about support for any other CMS, talk to us.

nodeVersion

  • Allowed values: a major version of Node.js as a string. Currently we support versions 12, 14, 16.
  • Required: No
  • Default: "14"

The version of Node.js used to install dependencies and run Node.js for Next.js and Gatsby.

Stackbit always uses the latest release of the major version you've specified. For example, if you specify "12", Stackbit will use the latest version for major 12 which is 12.21.0.

buildCommand

  • Allowed values: a string specifying the command to build your static site for production
  • Required: only if ssgName is set to custom.
  • Default: automatically configured by the framework set in ssgName , but you may want to customize it to your needs.

With our managed hosting, which is enabled by default, Stackbit also takes care to build the website with all production optimizations every time you hit the Publish button in the editor. To customize the command to run, use buildCommand.

Note that Next.js also supports dynamic features such as Server Side Rendering and on-demand image optimization, which require code to run when these are called. This is managed with no further configuration when you use our managed hosting and by external providers such as Netlify and Vercel.

publishDir

  • Allowed values: a string specifying a directory path relative to the project root
  • Required: Yes

The directory where generated static files are stored when the build command completes (see buildCommand property above)

For Next.js, the convention is to use the directory name out.

pagesDir

  • Allowed values: a string specifying a directory path relative to the project root, or null.
  • Required: When using the built-in Git CMS. For an API-based CMS, set to null.

Defines the root directory of page content. This works in tandem with model mapping.

dataDir

  • Allowed values: a string specifying a directory path relative to the project root, or null.
  • Required: When using the built-in Git CMS. For an API-based CMS, set to null.

Defines the root directory of non-page content, e.g. global configuration, team members or authors that are linked from multiple pages, and more. This works in tandem with model mapping.

pageLayoutKey

  • Allowed values: the property name in stored pages which defines their model type
  • Required: No
  • Default: layout

This property is explicitly set tolayout in all of our themes for backward compatibility. At this time, leave this value as is.

In future versions, both the default value (when this property is omitted) and the value explicitly set by our themes may change to type for more consistency with other content items. However, existing projects where this property is explicitly set will not be affected.

assets

  • Allowed values: an assets object
  • Required: When using the built-in Git CMS.

contentModels

Defines which content types can be added in the UI as pages or standalone non-pages, the URL mapping of pages, and more. See Mapping Content Models.

modelsSource

Allowed values: An object containing a list of directory paths, either in your project or its dependencies - see example.

Required: No

Default:

modelsSource:
  type: files
  modelDirs:
    - .stackbit/models

If you add additional entries to modelDirs, note that order is important: directories should be ordered in the property from lower to higher precedence. Models defined in higher precedence directories override models of the same name in the other locations, if such duplicates exist.

Usually, you do not need to change this property from its default value. However, this is useful for loading models defined in other 3rd party packages you've installed.

Be careful not to add any paths which are neither within your project nor its dependencies, as the project will not work properly in our visual editor and default hosting service.

For each of the directories in the list, Stackbit will search for model files (with either .yaml or .yml extension) in all sub-directories.

presetReferenceBehavior

⚠️ This options applies when using an API CMS, which is available as an add-on to our Business and Enterprise plans.

Specifies how to handle references when creating new content from a preset.

presetReferenceBehavior: copyReference | duplicateContents
Note that this affects only newly-created presets. Changing this value (or adjusting the exceptions below) have no affect on existing content created from presets.

Options:

  • copyReference (default): Reference(s) are copied directly. The new content will use the same references as the original content. (See duplicatableModels for providing exceptions.)
  • duplicateContents: Reference(s) are duplicated. The new content will refer to the newly duplicated content and will not affect the original referenced content. (See nonDuplicatableModels for providing exceptions.)

Example:

Suppose a PostFeed component preset that includes a reference to a list of featured posts. If copyReference is used, when new content is created, it will refer to the same posts stored in the preset.

If instead duplicateContents is used, each post referenced in the preset will be duplicated, and the new posts will be used for the new content.

duplicatableModels

when presetReferenceBehavior is set to copyReference, this field specifies a list of exceptions. If a model appears in this list, it will be duplicated. Every other model respects the copyReference setting.

presetReferenceBehavior: copyReference
duplicatableModels:
 - Post

nonDuplicatableModels

when presetReferenceBehavior is set to duplicateContents, this field specifies a list of exceptions. If a model appears in this list, it will NOT be duplicated. Every other model respects the duplicateContents setting.

presetReferenceBehavior: duplicateContents
nonDuplicatableModels:
 - Post