Docs (Public)

The stackbit.yaml file is where you provide the configuration and content models necessary for Stackbit to convert your theme to support other static site generators and to connect it to a CMS.

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

When you import a custom theme into Stackbit it will validate the theme based upon the stackbit.yaml file. During development, you can validate themes locally using the Unibit CLI.

npm install -g @stackbit/unibit
unibit validate

Basic stackbit.yaml

The following example shows an example of many of the typical fields you would need to include.

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. Generally it is recommended that you use ~0.2.0 (note the tilde), which 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

Supplying a supported static site generator name will set default values for a number of stackbit.yaml fields. For this reason, if you are importing a custom theme, it is recommende that you use custom to avoid setting default values which may not match your theme's unique structure.

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

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.

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

publishDir

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

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

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.

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

uploadDir

The directory contianing 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.

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

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.

Note that, due to limitations on certain CMS, only a single uploadDir can be specified.

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

This does not select a layout or template for your pages, which is handled by the underlying static site generator. This field enables explicit mapping of markdown files to page models via the page's front-matter. This is useful as an alternative to using the file matching features available when defining Page Models (i.e. folder, match, exclude and file). It is also a way to distinguish between pages that may meet the same matching requirements. Not that 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

Let's look at a simple example. In the below stackbit.yaml the pageLayoutkey is set to model_name. Two page models are defined (basic_model and contact_model)

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

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

# 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

A structure that 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 specific files from being matched by 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

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.

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

Examples

Open Source Themes

Check our Example 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. From there you can examine the stackbit.yaml.