The 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.

Stackbit Site Builder Diagram

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

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.

Depending on your headless-CMS, Stackbit Studio will work in one of the two modes - "API-based CMS mode" or "Git-based CMS mode".

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 stackbit.yaml.

In this mode, Stackbit Studio reads and writes content using headless-CMS API

Stackbit Studio with API-based CMS Diagram

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 stackbit.yaml.

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.

Stackbit Studio with API-based CMS Diagram

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 stackbit.yaml.

Stackbit Studio with Git-based CMS Diagram

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.

Stackbit Studio with Git-CMS Diagram

Git-CMS

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.

Configuring stackbit.yaml

Check the following sections to learn how to configure stackbit.yaml

Ready to get started?