stackbit.yaml

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

• Properties
  This section describes the base properties of stackbit.yaml and when to use them
• Assets
  Assets define how files, such as images, are stored and handled in a project
• Logic Fields
  List of fields used in static site generation logic.
• Models
  Models define the structure of site content
• Page models
  Page models define the structure of site pages
• Data models
  Data models define the structure of site data files such as JSON, TOML, or YAML
• Object models
  Object models define the structure of data nested inside page or data models
• Model Fields
  Model fields define the fields that make up a particular model
• Examples
  stackbit.yaml examples