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.
- Add a stackbit.yaml file to your site
- Import your site into Stackbit
- Learn how Stackbit's editor works
- Publish your site
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 -
.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.
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.
npm install -g @stackbit/cli
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.
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.
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:
- It clones your repository
- It checks-out the
- It installs your project dependencies by running
- It runs your Static Site Generator (SSG) development server, i.e.:
- 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.
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
previewbranch and pushed the changes to GitHub.
mainbranches. 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":
Click on the commit message to see the diff:
As you can see, Stackbit updated the
title field committed the change to the
To learn more about how Stackbit works with file-based content, read our conceptual guide.
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
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.