The stackbit.yaml file allows you to provide the configuration and content models necessary for the Stackbit Uniform conversion process. 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. Note: the filenames stackbit.yml and content-model.yml are also supported, but will be deprecated.

Prepare a Uniform theme

A Uniform theme need to conform to uniform theme requirements and need to have a valid stackbit.yaml with a valid content model.

Validate the theme with Unibit CLI

You can validate themes locally using the Unbit CLI. See the Unibit Installation guide if you do not already have Unibit installed via NPM.

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
dataDir: data      # folder with data files (yaml, json, toml)
pagesDir: content  # folder with markdown page files
pageLayoutKey: layout  # the front-matter key in markdown page files
                       # referencing their layout
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

The name of the static site generator your theme is built in. Tells Uniform which validation and conversion process to use. While this field is not required it is best practice to explicitly define this.

  • Example value: unibit
  • Allowed values: unibit, gatsby, hugo, jekyll or custom for any other static site generator you'd like to use
  • Default value: unibit
  • Required: false

If you try to validate or import a theme into Stackbit built in (for example) Hugo and you do not specify a value of 'hugo' it will fail. In this scenario, Uniform will use the default ssgNamevalue of "unibit" and when it tries to validate the themes "include" folder it will be search for a folder called "components" which will not exist because Hugo uses a different folder called "partials"

buildCommand

The build command that should be used to build the static site. If not specified, the default build command for the specified ssgName will be used. For example, in Gatsby the default command is gatsby build.

  • Example value: gatsby build
  • Allowed values: string
  • Default value: the default build command for specified ssgName
  • Required: false

uploadDir

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

After 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 directory.

  • Example value: images
  • Allowed values: string
  • Default value: none
  • Required: false

publishDir

The directory in which the SSG places the generated static site (typically after running the build command). If not specified, the default publish directory for the specified ssgName will be used. For example, in Jekyll the default publish directory is _site.

  • Example value: _site
  • Allowed values: string
  • Default value: the default publish directory for specified ssgName
  • Required: false

dataDir

The directory which contains data files (yaml, json, toml). If not specified, the default data dir for the specified ssgName will be used. For example, in Hugo the default data directory is data.

  • Example value: data
  • Allowed values: string
  • Default value: the default data directory for specified ssgName
  • Required: false

pagesDir

The directory for content files (*.md). If not specified, the default content directory for the specified ssgName will be used. For example, in Hugo the default content directory is content.

  • Example value: "content"
  • Allowed values: string
  • Default value: the default content directory for specified ssgName
  • Required: false

staticDir

The directory for static files. If not specified, the default static directory for the specified ssgName will be used. For example, in Hugo the default static directory is static.

  • Example value: static
  • Allowed values: string
  • Default value: the default static directory for specified ssgName
  • Required: false

pageLayoutKey

The front matter key in markdown files used to associate layouts. In most SSG's you can typically create layouts in the layouts or templates folder. Then in your content (*.md) files you can specify which layout to use in the front matter.

---
title: Home
layout: home # "layout:" is the pageLayoutKey, each SSG might have different layout keys
---

Welcome to the homepage

If not specified, the default value for the specified ssgName will be used. For example, the default pageLayoutKey for Jekyll and for Hugo is layout, for Gatsby it is template.

  • Example value: layout
  • Allowed values: string
  • Default value: the default layout key for specified ssgName
  • Required: false

models

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

Content Models

Field Models

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.

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

stackbit_banner

Displays a theme banner at the top of a Unibit site when you run unibit build. This banner has buttons to the theme's Github page and the Stackbit Importer.

Stackbit Banner

stackbit_banner:
    show_banner: true
    name: Fjord
    create_url: 'http://app.stackbit.com/create?theme=https://github.com/stackbithq/stackbit-theme-fjord'
    github_url: 'https://github.com/stackbithq/stackbit-theme-fjord'

init_js

Used only when ssgName is unibit

This field is required to properly load and execute JavaScript files included in a theme when it is converted into Gatsby. This field should specify a path to a javascript file, relative to the static folder, that should be executed when the site is loaded by the browser and renders the initial page. For example, when a theme is converted to Gatsby, the file specified by this property is wrapped by Gatsby's onInitialClientRender API method. This method is executed when Gatsby finishes the initial rendering of the page. Code in this file could be used to manipulate or attach global event handlers to window, html or body elements. It must not store references or attach event handlers to elements located inside the body element, as these could be replaced by Gatsby when router navigation occurs. When a single instance element, such as a container for a dialog or a prompt, needs to be attached to the body element when the page is loaded, it can be be done in this file as well. Successive router navigation actions will not remove elements located directly in body as Gatsby changes the DOM only below its special container element having id="___gatsby".

page_load_js

Used only when ssgName is unibit

Similar to init_js, this field should specify a path to a javascript file, relative to the static folder, that should be executed to manipulate contents of the body element for every rendered page. For example, when a theme is converted to Gatsby, the file specified by this property is wrapped by Gatsby's onRouteUpdate API method. This method is executed when React renders a new page and router history is changed. Code in this file could be used to manipulate or attach event listeners to elements inside the body element.

Full Example stackbit.yaml

This example uses the Unibit static site generator as defined in ssgName: unibit

stackbitVersion: ~0.2.0
ssgName: unibit
uploadDir: images
buildCommand: unibit build
publishDir: public
dataDir: data
pagesDir: content
staticDir: static
pageLayoutKey: layout
metadata:
  title: universal
  description: A starter theme for Unibit
  author: Stackbit
  authorURL: 'https://www.stackbit.com'
  images:
    small: images/demo-256x192.png
    large: images/demo-1024x768.png
models: 
  config: 
    type: config
    label: Config
    fields: 
      - type: image
        name: logo
        label: Logo
        description: the path of the logo image
        required: true
  home:
    type: page
    label: Home
    layout: home
    file: index.md
    hideContent: false
    singleInstance: true
    fields:
      - type: string
        name: title
        label: Title
        description: The title of the page.
        required: true
      - type: string
        name: heading
        label: Heading
        description: The heading displayed on the homepage
      - type: boolean
        name: show_button
        label: Show Button
        description: Show or hide the button on the hompage
      - type: string
        name: button_url
        label: Button URL
        description: URL the button links to
      - type: string
        name: button_text
        label: Button Text
        description: Text displayed in the button
  links:
    type: data
    file: links.json
    label: Supported Platforms 
    fields:
      - type: list
        name: ssg
        label: Static Site Generators
        description: A list of static site generators supported by Stackbit
        items:
          type: object
          labelField: title
          fields:
            - type: string
              name: title
              label: Title
              required: true
            - type: string
              name: url
              label: URL
              widget: url
              required: true
      - type: list
        name: cms
        label: Headless CMS
        description: A list of headless CMS supported by Stackbit
        items:
          type: object
          labelField: title
          fields:
            - type: string
              name: title
              label: Title
              required: true
            - type: string
              name: url
              label: URL
              widget: url
              required: true
  feature:
    type: page
    label: Feature
    layout: feature
    folder: features
    fields:
      - type: string
        name: title
        label: Title
        description: The title of the page.
        required: true
      - type: text
        name: description
        label: Description
        description: The text shown just below the features title.
      - type: image
        name: image_thumbnail
        label: Thumbnail Image
        description: The image shown in the feature.
      - type: number
        name: weight
        label: Weight
        description: Manually sort the order of the feature
      - type: string
        name: docs_button_url
        label: Button URL
        description: URL the button links to
      - type: string
        name: docs_button_text
        label: Button Text
        description: Text displayed in the button
      - type: boolean
        name: active
        label: Active
        description: Show/hide the feature on the features page
  features:
    type: page
    label: Features
    layout: features
    fields:
      - type: string
        name: title
        label: Title
        description: The title of the page.
        required: true