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
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:
We provide experimental support for the following SSGs:
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
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
stackbit.yaml file to your Github repo. The next time the Stackbit Studio loads it will read this file.