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
- Create a new project using the Stackbit Site Builder
- On the "Select A Theme" page choose "Custom Theme"
- Paste the Github URL of the theme and Stackbit will validate the theme, then press continue
- 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.
- Clones the Github repo where the theme is located
- Installs the theme
- Provisions the Stackbit Studio
- 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.