Properties help describe aspects of a site, theme or the repo used on Stackbit. Stackbit can infer some of these aspects, but it's best to be explicit to ensure the theme or site is fully compatible with Stackbit.

The following documentation describes stackbit.yaml version v0.3.

stackbitVersion

The version of stackbit.yaml file. Generally it is recommended that you use latest version with tilde ~0.3.0, which will use the latest applicable major version.

  • Allowed values: any valid version number using semver syntax
  • Default value: none
  • Required: true
  • Contexts: all

stackbitVersion example

stackbitVersion: ~0.3.0

ssgName

The name of the static site generator the underlying theme is created for. Attempts to set default values for specific static site generators. If you are importing a custom theme it is best to use custom to avoid setting default values which may not match your themes unique structure.

  • Allowed values: unibit, gatsby, hugo, jekyll or custom
  • Default value: unibit
  • Required: true
  • Contexts: theme

ssgName example

ssgName: custom

buildCommand

The build command that is used to build the static site. For example, for a Hugo site the command is normally hugo, for a Gatsby site it is normally gatsby build. However, this value does not need to be SSG centric. It can be any command line command or it can point to a shell script or custom build script as well.

  • Allowed values: String
  • Required: true
  • Contexts: theme

buildCommand example

buildCommand: hugo

publishDir

The directory in which the SSG publishes the generated static site (after running the build command). For example, for a Jekyll site the publish directory is normally _site.

  • Allowed values: Directory path relative to the project root
  • Required: true
  • Contexts: theme

publishDir example

publishDir: _site

staticDir

The directory containing static files that are not converted by the static site generator. For example, for a Hugo site the static directory is normally static. When using Netlify CMS the admin code will be placed in the defined directory path.

  • Allowed values: Directory path relative to the project root
  • Required: true
  • Contexts: theme, studio-git

staticDir example

staticDir: static

uploadDir

The directory containing media files that will be uploaded to a headless CMS. This value must be relative and nested inside staticDir folder. Normally this would the images folder inside the static directory.

  • Allowed values: Directory path relative to the staticDir directory path
  • Required: true
  • Contexts: theme, studio-git

uploadDir example

uploadDir: images

CMS assets usage

When connecting a theme with a CMS, all media assets from uploadDir are uploaded to the headless CMS. Stackbit replaces all image paths with the asset URL produced by a headless CMS. For this replacement to work, fields referencing images must be of type image, and the image path must match existing files using a path relative to the static folder.

pagesDir

The directory which contains page content files (*.md).

  • Allowed values: Directory path relative to the project root
  • Required: true
  • Contexts: theme, studio-git

pagesDir example

pagesDir: content

If you have multiple content folders in your project you may set pagesDir: "" which will scan for all markdown files in your theme. Keep in mind unwanted files like the README.md might be included and the validator will require a matching page model. You can explicitly exclude unwanted files using the excludePages field.

dataDir

The directory which contains data files (*.yaml, *.json, *.toml). For example, in Hugo the data directory is normally data.

  • Allowed values: Directory path relative to the project root
  • Default value: "" [an empty string, indicating the root folder]
  • Required: false
  • Contexts: theme, studio-git

dataDir example

dataDir: data

pageLayoutKey

The pageLayoutKey is used to match page content files to page models defined in stackbit.yaml. This field enables explicit mapping of markdown files to page models using a field from the front-matter. This is useful as an alternative to using the page models matching properties (folder, match, exclude and file), and when these properties are not enough to match between pages and their models. For example when pages of different models located in the same folder. If you set this field, you will need to add a layout field to all of your page models.

  • Allowed values: String
  • Required: false
  • Contexts: theme, studio-git

pageLayoutKey example

Let's look at an example. The following stackbit.yaml has pageLayoutkey set to model_name. Two page models are defined (basic_model and contact_model).

pageLayoutKey: model_name

models:
  basicpage:
    type: page
    label: Basic Page
    layout: basic_model
    fields:
          - type: string
            name: title
            label: Title
  contactpage:
    type: page
    label: Contact Page
    layout: contact_model
    fields:
          - type: string
            name: title
            label: Title

Now that the pageLayoutKey is defined, we can use that key in the front matter of the page to specify the model of the page.

# content/contact.md
---
title: contact
phone: 2423234234
email: test@test.com
# this page will use the "contactpage" page model.
model_name: contact_model 
---
# content/about.md
---
title: Home
# this page will use the "basicpage" page model.
model_name: basic_model
---

Welcome to the homepage

excludePages

Specify a glob string or a list of globs to exclude specific files from being matched by a page model.

  • Allowed values: A list of file paths with names. Also accepts glob patterns
  • Required: false
  • Contexts: theme, studio-git

excludePages example

excludePages: 
  - example/**/*
  - posts/index.md
  - README.md
models:
  page:
    type: page
    label: Page
    fields:
      - type: string
        name: title
        label: Title

metadata

Defines the information about your theme that will display to a user within the Stackbit app when they are choosing a theme. This field is not currently used by custom themes which are imported but may be in the future.

  • Allowed values: An object
  • Required: true
  • Contexts: theme

metadata example

metadata: 
  title: My Site Title
  description: Description of the site
  author: Stackbit
  authorURL: 'https://www.stackbit.com'
  images:
    small: images/demo-256x192.png
    large: images/demo-1024x768.png

models

An array of Models that define the site's content structure.

  • Contexts: all

Examples in the wild

Check our Example Themes for a list of open-source Github repos which include working stackbit.yaml files.

Ready to get started?