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

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.

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
.

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.

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
- PropertiesThis section describes the base properties of stackbit.yaml and when to use them
- AssetsAssets define how files, such as images, are stored and handled in a project
- Logic FieldsList of fields used in static site generation logic.
- ModelsModels define the structure of site content
- Page modelsPage models define the structure of site pages
- Data modelsData models define the structure of site data files such as JSON, TOML, or YAML
- Object modelsObject models define the structure of data nested inside page or data models
- Model FieldsModel fields define the fields that make up a particular model
- Examplesstackbit.yaml examples