Skip to content

Getting Started

Gatsby Theme Catalyst is an opinionated set of integrated themes and starters to accelerate your next Gatsby project. There is one “core” theme which is progressively built on top of until you have a complete site. This allows for better maintainability, choice for where to begin developing from, and a happy path for extendability using component shadowing.

This tutorial assumes the following:

  • That you understand Gatsby fundamentals
  • That you understand Gatsby themes

This tutorial will get you up and running with a barebones starter with content authored in MDX and minimal styling to make it easier to customize. If you want to test a more complete site you should check out gatsby-theme-catalyst-lithium.

Install the themes using a starter

This easiest way to get started is with a Gatsby starter. This tutorial will use gatsby-starter-catalyst which is intended as a solid begining point for further customization. A blank canvas if you will.

The themes included in this starter are:

# create a new Gatsby site using the basic starter
gatsby new catalyst
# change into your new directory
cd catalyst
# launch the site
gatsby develop

Update gatsby-config.js

Open gatsby-config.js and update the placeholder data. Most fields are common to other Gatsby sites or documented with inline comments. You can read more about specialized fields like socialLinks in the gatsby-config section of the docs.

Change your logo and social image

Replace content/assets/catalyst-site-logo.png, content/assets/catalyst-site-social.png, and content/assets/catalyst-site-icon.png. These files need to have the same name but can have different file types, e.g. they could be .jpg or .png.

catalyst-site-logo is used as the logo on the actual web pages.

catalyst-site-icon is used as the icon for the browser and offline mode. If you change this file make sure you update the options for gatsby-plugin-manifest as well or your will get an error.

catalyst-site-social is used as a fallback social media image if there is not a featured image in a blog post or on a page.

You can also do this via component shadowing for a more custom approach and future releases of Gatsby should enable a happier path for doing this with React suspense and GraphQL variables.

Create some content

By default content is authored using MDX. Go to content/pages/index.mdx to modify your home page. Note the SEO component on the top of the page which allows you to customize the metadata for each page.

Try pasting the following code into index.mdx:

<SEO title="Home" description="My Home Page"/>
# I am awesome
Yes you are!

Experiment with theme options

gatsby-theme-catalyst-core accepts a number of theme options which are used as feature flags for the theme. Take a look at the plugin array in gatsby-config.js and try changing some of these options.

resolve: `gatsby-theme-catalyst-core`,
options: {
//Default options are:
// contentPath: `content/pages`,
// assetPath: `content/assets`,
// displaySiteLogo: true,
// displaySiteTitle: true,
// displaySiteLogoMobile: true,
// displaySiteTitleMobile: true,
// invertSiteLogo: false,
// useStickyHeader: false,
// useSocialLinks: true,
// useColorMode: true,
// useKatex: false,
// remarkImagesWidth: 1440,
// imageQuality: 50,
//footerContentLocation: "left", // "left", "right", "center"

Experiment with Theme-UI

Open src/gatsby-plugin-theme-ui/index.js.

This is where you modify and change the theming for your site. You can read more about the integration with Theme-UI in the docs.

Try copy and pasting the following code into your theme file to see what happens.

import { merge } from "theme-ui"
import { BaseTheme } from "gatsby-theme-catalyst-core"
export default merge(BaseTheme, {
// Modifications to the base theme go here. This is an example changing colors and using variants to change your navigation links. Uncomment the code below to see what happens.
colors: {
background: "pink",
modes: {
dark: {
background: "purple",
variants: {
navLinks: {
border: "5px solid red",

Experiment with switching headers by switching themes

An integrated set of themes enables the power to dramatically change whole aspects of the design by just swapping out themes. This still an emerging area in Gatsby Theme Catalyst but it is interesting to see the opportunities this pattern enables in site design.

Goto gatsby-config.js and change your header just by changing the plugins array.

plugins: [
`gatsby-theme-catalyst-header-side`, // Remove gatsby-theme-catalyst-header-top

Get building

This should begin to give you an idea of what is possible with Gatsby Theme Catalyst and the launching pad it provides for developing your own Gatsby project.

For an example of a complete site check out gatsby-theme-catalyst-bery which adds a both a data layer ( and a presentation layer on top of the base starter covered here.

You can read more detail in the documentation about further customizing your themes and site.

© 2021 Gatsby Theme Catalyst