stackbit.yaml file lets you define the directory structure, the content schema, and other aspects of your site needed to make it work with Stackbit.
stackbit.yaml should be placed in the root of your project.
There are two use cases for
stackbit.yaml. The first use case serves Stackbit Site Builder and provides the data needed to create and configure a new site from a theme repository. The second use case serves Stackbit Studio and provides the necessary information to work with an existing site.
Both Stackbit Site Builder and Stackbit Studio can work without
stackbit.yaml. They will try to infer the missing data from project files. However, to support advanced capabilities and prevent misconfigurations, we recommend providing this file.
Stackbit Studio runs your static site generator and shows your site's live preview, enabling you and your collaborators to edit your site with an on-page editing experience and publish it.
When a user creates a site from a theme or imports an existing site, Stackbit Studio uses
stackbit.yaml to run your SSG. Once your SSG is up and running, Stackbit Studio shows the live site preview allowing you to edit your site pages, create new and delete existing pages, navigate your site via site-map, and other functionalities.
Stackbit Studio synchronizes site content in a bi-directional manner. When you make any content changes in Stackbit Studio, it immediately synchronizes these changes with the headless-CMS. Likewise, when you make any changes in the headless-CMS or the git repository, Stackbit Studio reflects them in live site preview.
stackbit.yaml install Stackbit CLI:
npm i @stackbit/cli -g
Then run the
validate command will validate the structure of your
stackbit.yaml and validate your site's content files against models defined in
Click here to learn more about Stackbit CLI.
The configuration of
stackbit.yaml might differ depending on the configuration of your site and the headless-CMS your
As explained in Conceptual Guides, if your site is pre-configured to work with a headless-CMS, such as NetlifyCMS or Contentful, then your site's content model is already defined in these CMS. Stackbit will use that content model, so you won't need to define the same content model again in
On the other hand, if your site does not use any headless-CMS and stores its content in plain files (md, JSON, YAML, etc.), you will need to define your site's content models in
stackbit.yaml using Models and Fields.
Read the following sections to learn how to configure