Introduction
In this tutorial we are going to create a new custom theme for Stackbit using Unibit. We will then convert it into another static site generator (Hugo) and connect it to a Headless CMS (DatoCMS)
If you wish to convert your theme into other static site generators the theme must be built with Unibit. You may also import themes built on other static site generators (like Gatsby) but they can only leverage the functionality that connects to Headless CMS and deployment etc.
Installing Unibit
npm install -g unibit
For more Unibit CLI commands see Unibit Installation Docs
Creating the basic site structure
Let's start by reviewing the basic file structure of a Unibit site.
└── my-theme
├── layouts
│ ├── body.html [required extends from base.html]
│ ├── home.html [extends from body.html]
├── components
│ ├── head.html [reserved, required]
│ ├── main.html [reserved, required]
├── content
│ ├── index.md
├── static
│ └── * [any static files will be copied to final site]
├── stackbit.yaml [required for importing theme in stackbit.com]
└── config.yaml
Create a new folder called my-theme
(or whatever you would like your sites project folder to be named). Create the following folders layouts
, components
, content
, static
.
config.yaml and stackbit.yaml
The config.yaml
and stackbit.yaml
files live in root directory and provide much of the sites global configuration.
Create a new file called config.yaml
- the config.yaml contains site properties that can be used in theme layouts.
# config.yaml
baseurl: "/"
title: "Universal"
params:
homepage_heading: "Universal Tutorial"
Create a new file called stackbit.yaml
- the stackbit.yaml is used to define a content model which enables conversion to other static site generators and connecting to a variety of headless CMS. We will cover this in more detail in Part 2 of the tutorial.
# stackbit.yaml
stackbitVersion: ~0.2.39
body.html layout
Create a new file called body.html
in the layouts
folder
{% extends "base.html" %} {% block body %}
<div class="wrapper">
{% block content %}{% endblock %}
</div>
{% endblock %}
body.html
is the only required layout file and it must extend from base.html
. Unibit uses Nunjucks templating and the extends
and block
tags are part of Nunjucks template inheritance.
base.html is an internal file that is generated by Unibit, you cannot edit or override it but body.html
must extend from it.
htmlhead.html and postbody.html components
For the base layouts to work we need to add 2 required components used by base.html
Create a new file called html_head.html
in the components
folder
<!-- components/html_head.html -->
<title>{% if page.title %}{{ page.title }} - {% endif %}{{ site.title }}</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
Create an empty file called post_body.html
in the components
folder
Homepage layout
Create a new layout called home.html
{% extends "body.html" %} {% block content %}
<h1>{{ site.params.homepage_heading }}</h1>
<h2>{{ page.params.sub_heading }}</h2>
{{ page.content }} {% endblock %}
Homepage content
Create new Markdown file index.md
with the following content:
---
title: Home
template: home
sub_heading: "Welcome to my custom Stackbit theme"
---
This is the homepage
Building the site
At this point we have all the required files to compile our site. Let's build the site using Unibit. From the sites root directory run the command
unibit build
You will see the build output in the terminal. The production ready static site has been generated into the /public/
folder. If you look inside the public folder you will see at this stage a single index.html
file. As you can see it as bundled all of the layouts together and the content from the markdown file has been injected into the content area.
To preview the site you can use a simple webserver to serve the files in the public
folder
npm install -g http-server
From the projects root directory run http-server ./public
Because Unibit is a superset of existing static site generators you can convert a Unibit site into a Hugo, Jekyll or Gatsby site (with more static site generators being added soon).
Converting Unibit into other SSG's is done using Stackbit. But before we can import our theme into Stackbit we need to add a stackbit.yaml
and define a content schema.
Defining a content model in the stackbit.yaml
Content models are defined in the stackbit.yaml
- there are many available properties and I recommend you read over the Content Model documentation.
We need to define 2 new content models.
- config model for the
config.yaml
- page model for the homepages
index.md
stackbitVersion: ~0.2.39
models:
config:
type: config
label: Global Site Config
fields:
- type: string
name: homepage_heading
label: Homepage Heading
description: The title displayed on the homepage.
home:
type: page
label: Home
template: home
file: index.md
singleInstance: true
fields:
- type: string
name: title
label: Title
description: The title of the page.
required: true
- type: string
name: sub_heading
label: Sub Heading
description: a subheading of the page.
Validating the content model
Before we import the theme and convert it we need to validate the Content Model using Unbit CLI.
unibit validate
Hopefully all the tests are passing. If so we are ready to import the custom theme into Stackbit.
Importing into Stackbit
Create a new Github Repo
At this stage, Stackbit can only import themes from Github. So you will need to create a new repository on your Github account and push your custom theme.
Import with Stackbit Via the Dashboard
- Create a Stackbit account
- Create a new project
- In the top corner where it says "Use Your Own Theme" click the Learn More link
- Paste the Github URL of your Unibit theme into the importer and then follow the steps to convert it.
Import with Stackbit Using Wizard Link
https://app.stackbit.com/wizard?privateThemeUrl=https://github.com/USERNAME/REPONAME&theme=custom
Troubleshooting importing
If you have only just created a Stackbit account you may see the following error when importing.
Can't connect to your repo. Please make sure it's public, or that Stackbit has the permissions required to access it. Retry Approving Permissions >
Normally this means you need to connect your Github account with Stackbit. Click the "Retry Approving Permissions" link and it should prompt you to authorize Stackbit with your Github.
Select a Static Site Generator
In the stackbit dashboard, select a static site generator you would like to convert to. For this tutorial we will choose "Hugo".
Select a CMS
For the CMS choose "No CMS"
Deploy Your Site
Once you have selected a SSG and CMS, you can click "connect accounts". Your Github account should already be authorized. Click "Create Project".
The converted site will be available on your Github in a new repo. I encourage you to clone it and take a look at the code, its a Hugo site!