Custom Themes - Documentation

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

Import Custom Theme Screenshot

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!

Ready to get started?

Try Stackbit Now