This section describes the base properties of stackbit.yaml and when to use them.

stackbitVersion

The version of the stackbit.yaml file. We recommend using the latest version with a 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

Example

stackbitVersion: ~0.3.0

ssgName

The name of the static site generator used in your project to generate a static site. You can use the custom value if none of the allowed values match your SSG.

  • Allowed values: gatsby, nextjs, hugo, jekyll, eleventy, gridsome, hexo, nuxt, sapper, vuepress or custom.
  • Required: true

Example

ssgName: jekyll

cmsName

The name of the CMS your project is configured to work with. If your project does not use any CMS, you don't need to specify this property.

  • Allowed values: contentful, sanity, netlifycms, forestry
  • Required: false

Example

cmsName: contentful

import

In case your theme is configured to work with an API-based CMS, such as Contentful. Stackbit Site Builder can handle the CMS provisioning when you, or any other user, import your theme into the Stackbit Site Builder and create a site. As part of the provisioning process, Stackbit Site Builder will create a CMS project, import the content schema and the initial content located in a special file previously exported from the CMS. It will also generate any keys required to access the content via API and setup any webhooks needed to trigger the deployment platform when the user publishes the content. To support this automatic provisioning, you will need to provide the import object that defines how to provision the CMS project.

For example, if your theme is using Gatsby and is configured to work with Contentful, you can export the content schema and the initial site contents into a JSON file. Specify the path to this file in the contentFile property. You should also provide the names of the environment variable names for the space ID and the Content Delivery API Token expected by gatsby-source-contentful plugin to connect with Contentful. Use spaceIdEnvVar and accessTokenEnvVar to specify the environment variable name for the space ID and the Content Delivery API Token, respectively.

In case your theme is configured to work with git-based CMS such as Forestry or NetlifyCMS, you don't need to specify the import property. These CMSes store their schemas and content files with project source files.

If you are importing an existing project already connected with a CMS, you don't need to provide the import property.

stackbit.yaml:

stackbitVersion: ~0.3.0
ssgName: gatsby
cmsName: contentful
import:
  type: contentful
  contentFile: contentful-export.json
  spaceIdEnvVar: CONTENTFUL_SPACE_ID
  accessTokenEnvVar: CONTENTFUL_ACCESS_TOKEN

contentful-export.json:

{
    "contentTypes": [...],
    "editorInterfaces": [...],
    "entries": [...],
    "assets": [...],
    "locales": [...],
    "webhooks": [...],
    "roles": [...]
}

Example of gatsby-config.js with gatsby-source-contentful configured to read spaceId and accessToken options from CONTENTFUL_SPACE_ID and CONTENTFUL_ACCESS_TOKEN environment variables:

module.exports = {
    plugins: [
        {
            resolve: `gatsby-source-contentful`,
            options: {
                spaceId: process.env.CONTENTFUL_SPACE_ID,
                accessToken: process.env.CONTENTFUL_ACCESS_TOKEN,
            },
        }
    ]
};

buildCommand

The build command that builds your static site.

For example, if your project uses Jekyll, the build command would be jekyll build, and if your project uses Gatsby, the build command would be gatsby build. However, this value does not have to be the standard SSG build command. You can specify any custom command such as npm run custom_build or node ./custom_build_script.js.

  • Allowed values: String
  • Required: true

Example

stackbitVersion: ~0.3.0
ssgName: jekyll
buildCommand: jekyll build

publishDir

The directory where the static site generator puts the generated static site files (after running the build command).

For example, if your project uses Jekyll, the publish directory would be _site, and if your project uses Next.js, the publish directory would be out.

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

Example

stackbitVersion: ~0.3.0
ssgName: jekyll
buildCommand: jekyll build
publishDir: _site

dataDir

The directory containing your site data files. Usually, data files have the *.yaml, *.json, and *.toml extensions.

For example, if your project uses Hugo, the directory containing your site data files would be data, and if your project uses Jekyll, this directory would be _data.

As with pagesDir, you can set this property to an empty string if your project's data files are located in different folders or the root folder.

If your project does not have page files, set this property to null. For example, if your project is configured to work with API-based CMS such as Contentful or Sanity, your data will be stored by the CMS. Therefore, this property would be null.

  • Allowed values: Directory path relative to the project root, or null
  • Required: true

Example

stackbitVersion: ~0.3.0
ssgName: hugo
dataDir: data

pagesDir

The directory containing your site pages' content files. Usually, page files have the .md extension (or .mdx in gatsby). For example, if your project uses Hugo, the directory containing your site pages would be content.

If you have multiple folders containing page content files, or if your page content files are located in the root folder like it is accepted in Jekyll and 11ty, you may set this property to an empty string pagesDir: "". Setting this property to an empty string will scan for all markdown files in your project. Keep in mind that Stackbit might include files unwanted like the README.md and the CONTRIBUTING.md. To fix that, you can explicitly exclude these files using the excludePages property.

If your project does not have page files, set this property to null. For example, if your project is configured to work with API-based CMS such as Contentful or Sanity, your pages' content will be stored by the CMS. Therefore, this property would be null.

  • Allowed values: Directory path relative to the project root, or null.
  • Required: true

Example

stackbitVersion: ~0.3.0
ssgName: hugo
pagesDir: content

excludePages

If your pagesDir contains files that have markdown extensions (.md, .mdx, .markdown) but should not be treated as site pages, use the excludePages property to specify which files should not be treated as site pages. The value should be a glob string or a list of glob strings matching files that should be excluded.

  • Allowed values: A list of file paths, or glob patterns
  • Required: false

Example

stackbitVersion: ~0.3.0
ssgName: jekyll
pagesDir: ""
excludePages: 
  - doc/**/*
  - README.md
  - CONTRIBUTING.md

assets

The assets object defines where the site assets, such as images, are stored and how page and data files reference these assets.

Note: If your project is configured to work with API-based CMS such as Contentful or Sanity, your assets will be stored by the CMS. Therefore, you don't need to use this property.
  • Allowed values: assets object
  • Required: true

logicFields

The logicFields list define the fields used in static site generation logic.

  • Allowed values: logicFields list of strings defining logic fields
  • Required: false

models

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

Ready to get started?