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

stackbitVersion

  • Allowed values: a string with any valid version number using semver syntax
  • Default value: none
  • Required: true

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.

Example

stackbitVersion: ~0.3.0

ssgName

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

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.

Example

ssgName: jekyll

ssgVersion

  • Allowed values: string with the version of your static site generator
  • Required: Required when using Hugo or other static site generator that doesn't specify its version in a dependency file.

Generally, you don't need to specify this property. Most of the static site generators such as Gatsby and Next.js specify their versions via package.json file. Other SSGs, like Jekyll, specify its version via Gemfile.

When a static site generator is not installed via dependency file, such as Hugo, Stackbit uses ssgVersion to manually download and install the correct version.

Example

ssgName: hugo
ssgVersion: 0.81.0

cmsName

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

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.

Example

cmsName: contentful

nodeVersion

  • Allowed values: Node.js version
  • Required: false
  • Default: 10

The Node.js version used to install dependencies and run Node.js based static site generator such as Gatsby or Next.js.

Stackbit always uses the latest major version of the version you specify. For example, if you specify 12.11.0, Stackbit will use the latest version for major 12 which is 12.21.0. For this reason, it is enough to specify only the major.

Example

ssgName: nextjs
nodeVersion: 12

import

  • Allowed values: import object
  • Required: required for themes using API-based CMS's

If your theme works with an API-based CMS, such as Contentful or Sanity, you might want to have an initial content which will be imported into the CMS when Stackbit creates a new site from your theme. The import object defines how to import the initial theme content into an API-based CMS.

Note: If your theme is configured to work with Git-based CMS such as Forestry or NetlifyCMS, you don't need to use this property. These CMS's store their schemas and content files with project source files.
If you have an existing project already connected with an API-based CMS, you don't need to use this property.

buildCommand

  • Allowed values: a string specifying the build command that builds your static site
  • Required: true

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.

Example

stackbitVersion: ~0.3.0
ssgName: jekyll
buildCommand: jekyll build

publishDir

  • Allowed values: a string specifying the directory path relative to the project root
  • Required: true

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.

Example

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

dataDir

  • Allowed values: a string specifying the directory path relative to the project root, or null
  • Required: true

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.

Example

stackbitVersion: ~0.3.0
ssgName: hugo
dataDir: data

pagesDir

  • Allowed values: a string specifying the directory path relative to the project root, or null.
  • Required: true

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 unwanted files 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.

Example

stackbitVersion: ~0.3.0
ssgName: hugo
pagesDir: content

excludePages

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

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.

Example

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

assets

  • Allowed values: assets object
  • Required: required for Git-based CMS's

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.

logicFields

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

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

models

  • Allowed values: an map of Models that define the site's content structure
  • Required: false