stackbit.yaml

The stackbit.yaml file is where you provide the configuration required by Stackbit. There are three main contexts where stackbit.yaml can be used. Every context determines what should go inside your stackbit.yaml file:

theme context: In this context stackbit.yaml provides the configuration required by Stackbit's Site Builder to create a new site from an existing theme. This configuration is used to provision the CMS with the Models and the initial content provided by the theme. Additionally, it is used to configure the deployment of the new site like the build command and publish directory.

studio context: In this context stackbit.yaml provides the configuration required to manage a site in Stackbit Studio. This configuration is used to configure Stackbit Studio options and behavior.

studio-git context: This context extends the studio context and is only used when there is no external headless-CMS involved, and the contents of a site are stored in files and committed to git. In this context, in addition to the configuration defined for studio context, stackbit.yaml should also provide Models and other data required to manage the site in Stackbit Studio.

The stackbit.yaml should be placed in the root directory of a theme or a site.

When you import a custom theme into Stackbit's Site Builder, it will validate the format of stackbit.yaml, and will validate the model against the theme content. During development, you can validate themes locally using the validator. You can also generate new stackbit.yaml from initial content in your theme.

Basic stackbit.yaml examples

The following examples show the typical fields you would need to include in stackbit.yaml in different contexts:

stackbit.yaml in studio context

In studio context, the schema of your site is provided by a headless-CMS. Therefore the configuration of stackbit.yaml should be minimal:

stackbitVersion: ~0.3.0
models:
  post:
    type: page
    urlPath: "/blog/{slug}"
  author:
    type: data

stackbit.yaml in studio-git contexts

In studio-git context, there is no headless-CMS and the content of the site is stored in git repo as markdown (.md) and data files (.json, .yml, .toml). In this case stackbit.yaml should include additional data describing the schema of your site and location of the content in repo.

stackbitVersion: ~0.3.0
staticDir: static  # folder with files that are copied to publishDir as is
uploadDir: images  # folder with media files, relative to staticDir
pagesDir: content  # folder with markdown page files
dataDir: data      # folder with data files (yaml, json, toml)
excludePages: 
  - example/**/*
  - README.md
models:
  # The schema of the theme or a site
  # see Models documentation for more info
  post: # a model called "post" 
    type: page
    label: Post
    folder: posts
    urlPath: "/blog/{slug}"
    fields: # array of fields
      ... # see Field documentation for more info

stackbit.yaml in theme context

In theme context, stackbit.yaml includes all the data required by Stackbit's Site Builder to generate a new site and provision headless-CMS with content schema and initial content of the site.

stackbitVersion: ~0.3.0
ssgName: custom
buildCommand: npm run build  # build command that builds static site
publishDir: dist   # folder with the generated static site files
staticDir: static  # folder with files that are copied to publishDir as is
uploadDir: images  # folder with media files, relative to staticDir
pagesDir: content  # folder with markdown page files
dataDir: data      # folder with data files (yaml, json, toml)
excludePages: 
  - example/**/*
  - README.md
models:
  ... # The schema of the theme or a site
      # see Models documentation

When Stackbit Site Builder creates a new site from a theme, it transforms the stackbit.yaml included with the theme into different stackbit.yaml matching the target context. That is, if the new site is powered by a headless-CMS, the stackbit.yaml will be transformed to match the studio context. On the other hand, if the new site will be powered by content that is stored in git repository, the stackbit.yaml will be transformed to match the studio-git context.