Custom Themes

You can now import custom themes into Stackbit. Custom themes could be an open source theme, your own personal theme or a new site you are building for a client or company. Custom themes should be built using the Jamstack (using a static site generator)

Why import a custom theme? Stackbit enhances Jamstack sites with live editing, previews and collaboration tools for publishers and clients - Learn more about these features

Getting Started

1. Build or use an existing theme

The theme you wish to import must be available in a public Github repo and it must be built using a static site generator. Try importing an example theme.

Custom Themes officially supports the following SSGs:

• Hugo
• Jekyll
• Gatsby

We provide experimental support for the following SSGs:

• Nextjs
• Eleventy
• Gridsome

There is nothing stopping you from trying to import themes built on other SSGs but they are largely untested and may fail frequently. We are actively working on improving support.

Need a theme? www.jamstackthemes.dev offers over 1000 public open source themes. Themes with a "create site" button can be imported into Stackbit instantly.

2. Import the theme

1. Create a new project using the Stackbit Site Builder
2. On the "Select A Theme" page choose "Custom Theme"
3. Paste the Github URL of the theme and Stackbit will validate the theme, then press continue
4. Complete the final steps and Stackbit will begin building your new site

3. Building the site

Stackbit goes through several steps to build a new site, these will happen automatically.

1. Clones the Github repo where the theme is located
2. Installs the theme
3. Provisions the Stackbit Studio
4. Deploys the site to Netlify

Once the build is successfull you will be taken to the Stackbit Studio where you can begin editing your site - Learn how to edit your site

Advanced

You can improve the Stackbit Studio experience by adding a stackbit.yaml file to your theme. Features like create/delete pages and inline editing require this file. Advanced stackbit.yaml documentation

1. Add a stackbit.yaml file

Create a new file called stackbit.yaml and add it to the root of your theme. Add the required base properties to the file. For more details on each property read base properties reference docs.

Basic stackbit.yaml example

stackbitVersion: ~0.3.0
# the name of the static site generator
ssgName: gatsby
# the build command that builds the static site
buildCommand: npm run build
# the folder where static site generator puts the generated site
publishDir: public
# the assets object defining how to handle project assets
assets:
  referenceType: static
  # the folder with static asset files
  staticDir: static
  # the folder within the staticDir where the uploaded files will be stored
  uploadDir: images
  # the URL path from which the static assets will be server
  publicPath: /
# the folder containing project's data files (yaml, json, toml)
dataDir: data
# the folder containing project's markdown page files (.md, .mdx, .markdown)
pagesDir: content
# list of globs matching the files that should be excluded from the pagesDir
excludePages:
  - README.md

2. Model your content

Stackbit 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. 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 name post in this example). Within that content model, model fields would defines the type and label for all of the front matter data.

3. Commit your changes

Push the stackbit.yaml file to your Github repo. The next time the Stackbit Studio loads it will read this file.