Custom Themes

You can import your own themes into Stackbit. Stackbit enabled themes can be connected to any Headless CMS in the Site Builder and they work with Stackbit Studio our innovative live editing experience for Jamstack sites.

Custom themes could be an open source theme, your own theme (in a private repo) or a new site you are building for a client or company.

Custom themes can be imported into the site builder here

Adding Stackbit

1. Build a Jamstack Theme

You should have an existing theme built using a static site generator. Currently we support the following SSG's: Hugo, Jekyll, Nextjs, Gatsby, Eleventy, Gridsome, Nuxt, Vuepress. Other SSG's might work (you can try and import them) but will likely fail.

2. Add a stackbit.yaml file

Create a new file called stackbit.yaml and add it to the root of your theme. This file helps Stackbit understand where your content and data files live, your content schema and things like the ssg and build command.

Basic stackbit.yaml example

stackbitVersion: ~0.3.0
ssgName: 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:
  ... # The schema of the theme or a site
      # see Models documentation - https://www.stackbit.com/docs/stackbit-yaml/models/

The full list of stackbit.yaml properties and their usage can be found here.

3. Model your content

Stackbit needs needs to understand your content in a structured format. You do this by defining content models in the stackbit.yaml. There are a lot of ways to define content models that we cover in detail here.

Basic Content Model Example

Let's say you have a blog theme with some markdown files for your blog posts.

A CMS must be able to a) create new blog posts b) edit blog posts and c) provide input fields in the GUI to edit individual front-matter fields. When you define content models you are writing a schema which tells the CMS where pages are located and what fields they have.

In our example, posts live in a posts folder under content:

├── content
│   └── posts
│       ├── learning-css-grid.md
│       └── flexbox-tutorial.md

Each post contains front-matter fields:

---
title: "Learning CSS Grid"
draft: true
thumbnail: "images/css-grid.png"
---

# CSS Grid is the new way to layout your pages

This is a blog post about using CSS grid to layout our pages...

In the stackbit.yaml we would create a content model for posts.

# stackbit.yaml
...
pagesDir: content
models: # content models go inside here
  post: # a page model called "post"
    type: page # the content model type, can be: page, data, object
    label: Post
    folder: posts # all .md files in `content/posts` will use this model
    fields: # define the frontmatter fields
      - type: string # this will use a  text input field in the CMS
        name: title # this identifies the front-matter field "title"
        label: Blog Post Title
      - type: boolean # this will use a toggle input in the CMS
        name: draft
        label: Save as a draft
      - type: image # this will use a file upload widget in the CMS
        name: thumbnail
        label: Blog Post Thumbnail

The stackbit.yaml for the above example would define where content is located (pagesDir) and then define the page model for the posts (given the label post in this example). Within that content model, a field model is created that defines the type and label for all of the front matter metadata.

4. Import your theme

Once you have modelled your content, it's time to import the theme into Stackbit. We will perform a range of tests to validate the theme. Once the import is complete, you'll be able to select any CMS and 1-click deploy to Netlify.

1. Create a new Stackbit project (No sign-up required)
2. On the "Select A Theme" page choose "Custom Theme"
3. Paste the Github URL of your theme, it will be validated and you'll be on your way to creating a new website.
4. You can also add a Create With Stackbit button to your Github project to allow anyone to launch new sites on Stackbit powered by your theme.

Stackbit.yaml Docs

Read our complete stackbit.yaml documentation