The 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
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.
Depending on your headless-CMS, Stackbit Studio will work in one of the two modes - "API-based CMS mode" or "File-based CMS mode".
Validating stackbit.yaml
To validate stackbit.yaml install Stackbit CLI:
npm i @stackbit/cli -g
Then run the validate command:
stackbit validate
The validate command will validate the structure of your stackbit.yaml and validate your site's content files against models defined in stackbit.yaml.
Click here to learn more about Stackbit CLI.
Configuring stackbit.yaml
The configuration of stackbit.yaml might differ depending on the configuration of your site and the headless-CMS your
site use.
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 stackbit.yaml.
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 stackbit.yaml
- PropertiesThis section describes the base properties of stackbit.yaml and when to use them
- ImportImporting initial theme content into the CMS
- 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