In this tutorial, we will go through the necessary steps required to import an existing Jamstack website into Stackbit and edit it with Stackbit editor.

  1. Create a new Gatsby site
  2. Add a Stackbit configuration file
  3. Import your site into Stackbit
  4. Learn how Stackbit's editor works
  5. Add a new field to a page
  6. Publish your site
Prerequisites: You'll need to have a GitHub account.

Step 1: Create a new Gatsby site

For the purpose of this tutorial we’ll clone a popular Gatsby starter template.

First, install the Gatsby CLI

npm install -g gatsby-cli

Then, run the following command to download a Gatsby starter into the my-blog-starter folder, initialize a local git repository, and install dependencies.

gatsby new my-blog-starter https://github.com/gatsbyjs/gatsby-starter-blog

Now let's create a GitHub repository to host your site's code. Click here to create a new repository in your GitHub account. Name the repository my-blog-starter. You can set it to be public or private. Don't initialize it with README, .gitignore, or license files - leave all checkboxes unchecked.

Push your local repository to GitHub by running the following command (replace <remote-url> with your GitHub Remote URL):

cd my-blog-starter
git remote add origin <remote-url>
git push -u origin master
☝️ You can specify the <remote-url> using two different formats - an HTTPS https://github.com/USERNAME/REPOSITORY.git or an SSH git@github.com:USERNAME/REPOSITORY.git. To learn more, read GitHub's guide Which remote URL should I use?

Step 2: Add the Stackbit Configuration

Before importing your site into Stackbit, let's create the stackbit.yaml file that will tell Stackbit how to import and run the preview of your site. This file will also include your site's content model; this will allow editing your site's content via Stackbit on-page editor.

Create a file named stackbit.yaml in the my-blog-starter folder and paste there the following code.

stackbitVersion: ~0.3.0

# The name of the static-site-generator
ssgName: gatsby

# Use node version 12
nodeVersion: '12'

# The site has no data files (json, yaml, .etc)
dataDir: null

# The folder with markdown files representing your site pages
pagesDir: content

# This site uses "relative" assets pattern. That is, asset files are referenced
# from content files using relative paths
assets:
  # asset are referenced using relative paths
  referenceType: relative
  # the common ancestor folder that contains all site images
  # is the root '' folder
  assetsDir: ''
  # uploaded images will be stored in 'src/images'
  uploadDir: src/images

# Models describe the content structure of your site pages and data
models:
  # The "post" model describes the post pages
  post:
    type: page
    label: Post
    # Post pages are loaded from this folder (relative to pagesDir)
    folder: blog
    # Let Stackbit know how to compute URL paths of your pages
    urlPath: "/{slug}"
    # Pages created in Stackbit will be stored in the following location
    # (relative to pagesDir)
    filePath: "blog/{slug}/index.md"
    # The fields of the post page
    fields:
      - type: string
        name: title
      - type: date
        name: date
      - type: text
        name: description

In short, this file tells Stackbit which static site generator your site uses, what environment it needs to run in, and the information about the content model of your site. To learn more about stackbit.yaml and how to configure it visit stackbit.yaml documentation.

To validate the stackbit.yaml and the site's content against the schema defined in stackbit.yaml, we will use Stackbit CLI. Install the Stackbit validator by running:

npm install -g @stackbit/cli

Then run the following command inside the my-blog-starter folder:

stackbit validate

You should see the following output:

loading and validating Stackbit configuration from: .../my-blog-starter
  ✔ configuration is valid
loading and validating content from: .../my-blog-starter
  loaded 3 files in total (3 matched, 0 unmatched)
  3 files matched to models:
    post: 3 files:
      content/blog/hello-world/index.md
      content/blog/my-second-post/index.md
      content/blog/new-beginnings/index.md
  ✔ content files are valid
✔ validation passed

The validator checks that stackbit.yaml format is valid and conforms to the stackbit.yaml specification. Then, it loads the content files according to the configuration defined in stackbit.yaml and matches them to models. In our case, we have defined a single page model called post that describes files located in the content/blog folder. Finally, it validates the loaded files against the models defined in stackbit.yaml. Click here to learn more about Stackbit CLI.

Run the following commands to commit and push the changes to your GitHub repository:

git add stackbit.yaml
git commit -m "Added stackbit.yaml"
git push

Step 3: Import your site into Stackbit

Navigate to https://app.stackbit.com/import to import your site into Stackbit. You will need to connect Stackbit with your GitHub account. After connecting, select the my-blog-starter repository from the list of repositories in your GitHub account. Stackbit will load your repository and select the master branch for you. From this branch Stackbit will create a new preview branch that will be used by Stackbit.

Stackbit Import Site

Click Continue, then click Go on the next screen. Stackbit will now load the preview of your site by running the following steps:

  1. It clones your repository
  2. It checks-out the preview branch
  3. It installs your project dependencies by running npm install
  4. It runs Gatsby's development server, i.e.: gatsby develop
  5. It routes any page requests made from your browser to Gatsby's development server

You can open the Logs panel at the bottom of the screen to see these steps' logs. When Stackbit finishes running all these steps, you will see your site's live preview served by the Gatsby development server.

Preview Logs

☝️ When importing a different site, the Logs panel can help you debug any issues that might cause your site not to load.

To learn more about how Stackbit Preview works, read our conceptual guide.

Step 4: Learn how Stackbit's editor works

After Stackbit loads your site, it will enter the "Edit" mode. In the "Edit" mode, when you move your mouse pointer around, the editor shows rectangular guides around editable content. Clicking inside the rectangular area will activate the on-page editor and let you edit the underlying source value.

Click on the "New Beginnings" title and change its text to something else, then press enter. When editing a text, the rectangle around the text becomes green, and when the change is being saved, the rectangle becomes orange.

Click to edit

What just happened?

When you changed the text, Stackbit did the following steps:

  • Stackbit updated the markdown file containing the original text inside the preview server.
  • Gatsby picked up the updated file and updated the live preview via web-socket.
  • Stackbit committed the change within the markdown file into the special preview branch and pushed the changes to GitHub.
☝️ Stackbit never commits content changes to the master or the main branches. This is to ensure that your changes will not be picked up by a serverless deployment platform such as Netlify, affecting your live site.

Let's look at the git commit with the updated markdown file. To quickly open your site's repository, click on the "Settings" button in the top bar. Then click on the "Open" button beside the GitHub repository section.

In GitHub, select the preview branch and click the "commits" link to see the latest commits. You should see that the latest commit has the following commit message "index.md: updated title":

Git preview commits

Click on the commit message to see the diff:

Git commit diff

As you can see, Stackbit updated the title field of the blog post and committed the change to the preview branch.

To learn more about how Stackbit works with file-based content, read our conceptual guide.

Step 5: Add a new field to a page

Wouldn't it be nice if every post had a featured image shown in the blog feed?

Let's add a featuredImage field to the post model and use that image in the React component of the index.js page.

☝️ Before making any changes, checkout the preview branch. Remember, Stackbit preview works with the preview branch only. Stackbit Editor will not reflect changes made on other branches.
git fetch
git checkout preview
  • Open the stackbit.yaml and add a new featuredImage field of type image to the post model under the description field:

    @@ -40,4 +40,6 @@ models:
           - type: date
             name: date
           - type: text
             name: description
    +      - type: image
    +        name: featuredImage
    
  • Add featuredImage field to GraphQL schema customization in gatsby-node.js:

    @@ -105,7 +105,8 @@ exports.createSchemaCustomization = ({ actions }) => {
         type Frontmatter {
           title: String
           description: String
           date: Date @dateformat
    +      featuredImage: File @fileByRelativePath
         }
    
         type Fields {
    
  • Add featureImage field to GraphQL query in src/pages/index.js:

    @@ -81,8 +83,13 @@ export const pageQuery = graphql`
             frontmatter {
               date(formatString: "MMMM DD, YYYY")
               title
               description
    +          featuredImage {
    +            childImageSharp {
    +              gatsbyImageData(width: 800)
    +            }
    +          }
             }
           }
         }
       }
    
  • Import GatsbyImage and getImage in src/pages/index.js

    @@ -1,5 +1,6 @@
     import * as React from "react"
     import { Link, graphql } from "gatsby"
    +import { GatsbyImage, getImage } from "gatsby-plugin-image"
    
     import Bio from "../components/bio"
     import Layout from "../components/layout"
    
  • Add <GatsbyImage> with the featuredImage between the post's <header> and <section> elements in src/pages/index.js:

    @@ -46,6 +47,7 @@
         </h2>
         <small>{post.frontmatter.date}</small>
       </header>
    +  <GatsbyImage image={getImage(post.frontmatter.featuredImage)} alt={post.frontmatter.title} />
       <section>
         <p
           dangerouslySetInnerHTML={{
    

Commit and push the changes to your GitHub repository (double-check that you are on the preview branch):

git add .
git commit -m "Added featuredImage to posts"
git push

As soon as you push your changes, GitHub will notify Stackbit about the new commits on the preview branch, and Stackbit will pull the latest code. Now you will be able to add new featured images to your post!

Click on the area between the post title and description to open the editor for the post object. Then expand the "Featured Image" field and click on the "Upload" button to upload a new image.

Upload an Image

Once uploaded, the image will appear under the blog post title:

Uploaded an Image

What happened?

Stackbit saved your image in the src/images folder and updated the featuredImage field in the markdown file to the image path relative to the markdown file itself:

title: 'New Beginnings :)'
date: '2015-05-28T22:40:32.169Z'
description: >-
  This is a custom description for SEO and Open Graph purposes, rather than the
  default generated excerpt. Simply add a description field to the frontmatter.
featuredImage: ../../../src/images/waves.jpg

This behavior is defined with the assets objects in stackbit.yaml.

Step 6: Publish your site

Now, your site is ready to be published. Click the "Publish" button in the top right to publish your site. Stackbit will merge the preview branch into the master branch.

You can set up your site with a serverless deployment platform such as Netlify or Vercel. These platforms will deploy and publish your site whenever new commits are pushed to the master branch, effectively deploying your changes whenever you click the "Publish" button in Stackbit.