stackbit.yaml file lets you define the directory structure, the content schema, and other aspects of your site needed to make your theme, or project, work with Stackbit. This file 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. The second use case serves Stackbit Studio and provides the necessary data to manage 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 Site Builder
Stackbit Site Builder converts a Jamstack theme located in a git repository into a functioning Jamstack site.
When a user imports a Jamstack theme built with one of the existing static site generators (SSG), Stackbit Site Builder uses the configuration defined in
stackbit.yaml to create and configure a new Jamstack site. The site creation process involves creating and provisioning a new git repository, a new headless-CMS project, and a new serverless deployment platform project such as Netlify.
For example, Stackbit Site Builder uses the Models and the Fields defined in
stackbit.yaml to provision the headless-CMS with the content schema and the initial content. If your theme is pre-configured to work with a specific headless-CMS, such as NetlifyCMS, Stackbit Site Builder will create a Jamstack site configured to work with NetlifyCMS. In this case, you don't need to define the content schema in
stackbit.yaml as it is already available in NetlifyCMS configuration files.
When you import a theme into Stackbit Site Builder, it will validate the format of your
stackbit.yaml and will validate the content schema against the content files.
After Stackbit Site Builder creates a new site, the
stackbit.yaml continues to serve Stackbit Studio.
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 inline editing experience and publish it.
When a user creates a site via Stackbit Site Builder 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.
API-based CMS mode
Stackbit Studio works in this mode when your site is configured to work with an API-based CMS such as Contentful or Sanity. Stackbit Studio fetches your site's content schema from the headless-CMS, so you don't need to define it in
In this mode, Stackbit Studio reads and writes content using headless-CMS API
Git-based CMS mode
Stackbit Studio works in this mode when your project is configured to work with a Git-based CMS such as NetlifyCMS, Forestry, or Git-CMS. The Git-CMS is used when there is no pre-configured CMS, and your site's content schema is defined in
In this mode, Stackbit Studio reads and writes content from the content files such as markdown files (.md, .mdx) and data files (.json, .yaml), and persists them using git commits. Stackbit Studio creates a special
preview branch that it uses to persist your unpublished content changes. When you decide to publish your site, Stackbit Studio merges the
preview into the
master branch, and the serverless deployment platform deploys your site.
When your site is integrated with a headless-CMS that defines your site's content schema in its configuration files, Stackbit Studio will use that content schema, so you don't need to define it in
On the other hand, if your project does not use any headless-CMS and stores the content in plain files (.md, .json, .yaml, etc.), you can use Git-CMS by defining your site's content schema in
stackbit.yaml using Models and Fields.
The configuration of
stackbit.yaml might differ depending on the headless-CMS your project use.
As noted before, if your theme, or site, is pre-configured to work with a headless-CMS other than git-CMS, such as NetlifyCMS. Then it already has the content schema defined in the NetlifyCMS configuration. Stackbit will use NetlifyCMS configuration, so you won't have to define the same schema again in
stackbit.yaml. On the other hand, if your project does not use any headless-CMS and stores the content in git as plain files (md, JSON, YAML, etc.), you will need to define your site's content schema in
stackbit.yaml with Models and Fields.
Check the following sections to learn how to configure