Setting up gatsby-theme-catalyst-sanity
gatsby-theme-catalyst-sanity is a “core” theme for integrating SANITY.io into Catalyst. This means it focuses on function and utility with minimal visual styles. It is designed as a jumping off point for further customization and development work before being deployed. SANITY.io is a headless CMS that provides a GUI for content authoring and data entry - meaning your clients/users are not editing markdown.
This tutorial assumes you have basic familiarity with Gatsby and modern web development practices.
Install the theme using a starter
# create a new Gatsby site using the starter sitegatsby new catalyst-sanity https://github.com/ehowey/gatsby-starter-catalyst-sanity
Install SANITY.io
npm install -g @sanity/cli
Initialize SANITY.io and setup your content studio
# Move to the starter directorycd catalyst-sanity# Move to the content studio directorycd sanity-studio# Initialize SANITYsanity init# Answer YES to reconfiguring the studio? The current folder contains a configured Sanity studio. Would you like to reconfigure it? Y# Register or login to SANITY following their promptsGood stuff, you are now authenticated. You will need a project to keep yourdatasets and collaborators safe and snug.# Create a new SANITY project? Select project to use (Use arrow keys)❯ Create new project# Give your project a name? Your project name: Catalyst# Use the default dataset configuration? Use the default dataset configuration? (Y/n) Y# Import starter dataset, select "production" dataset when promptedcd datasanity dataset import production.tar.gz# Deploy the graphql schemacd ..sanity graphql deploy# Start your studio on a localhostsanity startContent Studio successfully compiled! Go to http://localhost:3333
Congratulations! You should be looking at the new backend for your website! You can update data now or just leave it for later.
Update sanityProjectId
In order to properly source your data you need to update the theme options for gatsby-theme-catalyst-sanity
to give it the correct project id. The easiest way to do this is to open sanity-studio/sanity.json
and at the top of the file you should see the project id like this:
// In sanity.json"api": {"projectId": "c1x70rzt", // This is what you need"dataset": "production"},
Now open gatsby-config.js
and update the theme option with the correct project id like this:
{resolve: `gatsby-theme-catalyst-sanity`,options: {sanityProjectId: `c1x70rzt`, // Change this line},},
You can also do this using environment variables, if you setup a private dataset with a token you need to use environment variables to ensure it is not committed to your version control.
Run ‘gatsby develop’ for the first time
Now that you have the content studio setup you are ready to fire up your site for the first time! Because of how SANITY.io is integrated it is normal for you to see some warnings in your console log about GraphQL queries, these are warnings only and not errors.
# Get back to your root directory from /sanity-studiocd ..# gatsby develop to start your development servergatsby develop
Nice work you did it! You can remove the folder /sanity-studio/data
you don’t need it anymore. And committing it to your git repo is unnecessary.
Experiment with theme options to control building pages
gatsby-theme-catalyst-sanity
was designed as a “core” theme with a number of different theme options to control the createPages API. This means that you can enable/disable certain functionality for your end user without having to create a custom content studio.
For example - if you want to disable and turn off the blog you would do the following. In gatsby-config.js
:
{resolve: `gatsby-theme-catalyst-sanity`,options: {// Example for an env variable// sanityProjectId: process.env.SANITY_PROJECT_ID,// sanityDataset: process.env.SANITY_DATASET,// sanityToken: process.env.SANITY_TOKEN,//// Default options are:// sanityProjectId: "abc123" // Required// sanityDataset: "production"// sanityToken: null// sanityWatchMode: true// sanityOverlayDrafts: false // Token is required for this// sanityCreatePages: truesanityCreatePosts: false,sanityCreatePostsList: false,// sanityCreateProjects: true// sanityCreateProjectsList: true// sanityPostPath: "/posts"// sanityProjectPath: "/projects"// useSanityTheme: false // Experimental right nowsanityProjectId: "p9a6h8j1",},},
In sanity-studio/structure/deskStructure.js
remove these lines to hide the posts GUI:
S.listItem().title("Posts").child(S.documentTypeList("post").title("Posts")),
Remove any links or references to the post pages and presto - no more blog.
If you see an error when you try to navigate to the posts index or a post page you need to run
gatsby clean
- because of the cached pages it can throw this error:Error: EnsureResources was not able to find resources for path: "/posts"
Try playing around with a few of the different theme options to see what you can make happen.
Deploy the content studio
Right now the content studio is only locally deployed, which means you can change it from your computer however if you run sanity deploy
inside of catalyst-writer/sanity-studio
you can deploy it to a https://studio-name.sanity.studio
domain for free making it accessible remotely.
Explore the SANITY.io content studio and add your own data
The dataset you imported comes with placeholder data to get you started. Play around with the data and see what happens. You should see live updates on your local site in development mode because of real time previews with watch mode. You may occassionally need to restart the Gatsby development server (gatsby develop
) to see certain changes.
Push to GitHub and deploy your site
There are a few different ways to do this and publish your website. This is what works best for me:
Setup a webhook to automatically redeploy when content updates
Because your content is separate from the git repository you will need a webhook to ensure your site redeploys when the content in SANITY changes. Both Netlify and Gatsby have good information in their docs about using webhooks.
# Get back to your sanity foldercd sanity-studio# Setup the webhook, e.g. is for Netlifysanity hook create? Hook name: netlify? Select dataset hook should apply to: <yourDataset>? Hook URL: https://api.netlify.com/build_hooks/<someId>
Setup siteUrl in gatsby-config.js
Most site metadata is generated from SANITY however generating both robots.txt
and sitemap.xml
depend on a properly defined siteUrl
field found in gatsby-config.js
. There is also a field for this in your Site Settings within SANITY, you need to fill these both in.
module.exports = {siteMetadata: {siteUrl: `https://www.example.com`, //Change to you site address, required for sitemap.xml and robots.txt file among other things],},}
Next steps
You can use this theme as a starting point for creating your own custom SANITY.io and Gatsby site. To see an example of how this is done you can look at the source code for gatsby-theme-catalyst-hydrogen as this will show you an example of layering a presentation theme on top of the data theme.
I would love to hear about your results and see what you create!