Overview

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:

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