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
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.
- Create a new Stackbit project (No sign-up required)
- On the "Select A Theme" page choose "Custom Theme"
- Paste the Github URL of your theme, it will be validated and you'll be on your way to creating a new website.
- 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.
Read our complete stackbit.yaml documentation