Import an Existing Site into Stackbit

In this tutorial, we'll go through the necessary steps to bring your existing Jamstack site to Stackbit and start taking advantage of Stackbit's editing and collaboration tools.

1. Prerequisites
2. Add a stackbit.yaml file to your site
3. Import your site into Stackbit
4. Learn how Stackbit's editor works
5. Publish your site

Prerequisites

Please note the following limitations when importing a site into Stackbit:

• You have access to your website's code repository on GitHub. If you don't have one handy, you can fork this blog boilerplate for Gatsby.
• Stackbit supports sites built using one of the following SSGs - Gatsby, Next.js, Eleventy, Gridsome, Hexo, Hugo, Jekyll, Next.js, Nuxt, Sapper, Vuepress.
• Your site's content must be separated from the presentation. For example, if your site uses React, then the content should be stored separately and passed to React components via props. If you want to learn more about separating content from presentation, read our conceptual guide on this subject.
• Your site's content is stored in files in your site's git repository. These files should have one of the following extensions - .md, .mdx, .markdown, .yaml, .yml, .json, .toml. Alternatively, your site's content is managed by one of the supported CMSs - Contentful, Sanity, Forestry, NetlifyCMS.
• Your site has a working development server that listens to content changes in files or headless CMS and refreshes any opened browser sessions via live-reload or HMR when the content is changed.

Step 1: Add a stackbit.yaml file to your site

Before importing your site into Stackbit, let's create a configuration file that will tell Stackbit how to import and run the preview of your site correctly and provide advanced features such as the on-page editing experience.

Install Stackbit CLI

npm install -g @stackbit/cli

Generate the configuration file (stackbit.yaml) for your site or custom starter repository

cd my-website
stackbit init

In short, this file tells Stackbit which Static Site Generator (SSG) your site uses, what environment it needs to run in, and the information about the content structure of your site. To learn more about stackbit.yaml and how to configure it visit stackbit.yaml documentation.

Add the stackbit.yaml to your repository

git add stackbit.yaml
git commit -m 'add stackbit.yaml'
git push

Note that the generated stackbit.yaml is the "best guess", so it might not have the best content model for your site. For example, fields that could store markdown content might be marked as strings. After generating the stackbit.yaml file, we recommend reviewing it and adjusting it if needed. We also recommend running the validate command to check if there are content files without matched models.

Click here to learn more about Stackbit CLI.

Step 2: 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 your website's 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.

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 your Static Site Generator (SSG) development server, i.e.: gatsby develop
5. It routes any page requests made from your browser to your Static Site Generator development server

You can open the Logs panel at the left 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 your SSG development server.

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

Step 3: 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 a 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.

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.
• The SSG server 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.

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":

Click on the commit message to see the diff:

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

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

Step 4: 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.