The stackbit.yaml file allows you to provide the configuration and content models necessary for Stackbit to convert your theme. It is used when converting into other static site generators and when connecting headless CMS.

The stackbit.yaml should be placed in the site's root directory.

When you import a Uniform theme into Stackbit it will validate the theme. For a faster development flow you can also validate themes locally using the Unibit CLI.

npm install -g @stackbit/unibit
unibit validate

Basic Example stackbit.yaml

stackbitVersion: ~0.2.0
ssgName: custom    # allowed values: unibit, jekyll, hugo, gatsby, custom
buildCommand: npm run build  # build command that builds static site
publishDir: dist   # folder with the generated static site files
staticDir: static  # folder with files that are copied to publishDir as is
uploadDir: images  # folder with media files, relative to staticDir
pagesDir: content  # folder with markdown page files
dataDir: data      # folder with data files (yaml, json, toml)
excludePages: 
  - example/**/*
  - README.md
models:
  ... # see Stackbit Content Model documentation

stackbit.yaml Fields

stackbitVersion

The Stackbit Uniform version to use. Useful if you want to use a specific version or a development version. Otherwise using ~0.2.0 (note the tilde) will fetch the latest version automatically.

  • Example value: ~0.2.0
  • Allowed values: any valid version number using semver syntax
  • Default value: none
  • Required: true

ssgName

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.

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

buildCommand

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

  • Example value: "hugo"
  • Allowed values: string
  • Required: true

publishDir

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

  • Example value: "public"
  • Allowed values: string
  • Required: required

staticDir

The directory for static files. For example, in Hugo site the static directory is normally static.

  • Example value: "static"
  • Allowed values: string
  • Required: true

uploadDir

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

  • Example value: images
  • Allowed values: string
  • Required: true

When connecting a theme with a CMS, all media assets from uploadDir are uploaded to a 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 by a path relative to the static folder.

pagesDir

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

  • Example value: "content"
  • Allowed values: string
  • Required: true

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

  • Example value: data
  • Allowed values: string
  • Default value: "" [an empty string, indicating the root folder]
  • Required: false

pageLayoutKey

The pageLayoutKey is not related to selecting a layout or template for your pages, the underlying ssg remains in charge of this. This field enables explicit mapping of markdown files to page models from the front-matter. This is an alternative to using the Page Models matching features folder, match, exclude and file. It is also a way to distinguish between pages that meet the same matching requirements. If you set this field, you will need to add a layout field to all of your page models.

  • Example value: "model_name"
  • Allowed values: string
  • Required: false
# stackbit.yaml
pageLayoutKey: model_name
models:
    basicpage:
        type: page
        label: Basic Page
        match: *.md
        layout: basic_model
        fields:
            ...
    contactpage:
        type: page
        match: *.md
        label: Contact Page
        layout: contact_model
        fields:
            ...
# content/contact.md
---
title: contact
phone: 2423234234
email: test@test.com
model_name: contact_model # this page will use the "contactpage" page model.
---
# content/about.md - this page will continue to use the 
# "basicpage" model because no `model_name` has been set
---
title: Home
---

Welcome to the homepage

models

Defines the site's content models which contain field models.

Content Models

Field Models

excludePages

Specify a glob string or a list of globs to exclude files from needing to be matched to a page model.

  • Example value: ['example/*/', 'README.md']
  • Allowed values: an array of glob strings
  • Required: false
excludePages: 
  - example/**/*
  - posts/index.md
  - README.md
models:
  page:
    type: page
    label: Page
    fields:
      ...

metadata

metadata is used to display information about your theme in the Stackbit app when a user clicks "create new project" and is choosing a theme. This field is not currently used by custom themes which are imported but may be in the future.

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

More Examples

Example Open Source Themes

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

Stackbit Themes

You can examine the source code of all of the themes available in Stackbit. Launch Stackbit and select a theme and an ssg. Create the site and the code will be generated in your own Github account. There you can examine the stackbit.yaml.