Skip to content

Getting Started

Gatsby Theme Catalyst is an opinionated set of integrated themes and starters to accelerateyour next Gatsby project. The vision is one “core” theme which is progressively built on top of until you have a complete site. This allows for easier maintainability, choice about whether you want to start with a barebones starter or a more complete site, and a happy path for extendability using component shadowing.

This tutorial assumes the following:

This tutorial will get you up and running with a barebones starter with content authored in MDX which has minimal styles so it is easier to customize and make your own. If you want to test a more complete site you should check out gatsby-theme-catalyst-helium.

Install the themes using a starter

This easiest way to get started is with a starter. This tutorial will use gatsby-starter-catalyst which is intended as a solid starting point for further customization.

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.

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.

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

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

Create some content

By default in this starter 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 in 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,
        // invertLogo: false,
        // useStickyHeader: false,
        // useSocialLinks: true,
        // useColorMode: true,
// useKatex: false,
        // remarkImagesWidth: 1440,
        //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 site.

For an example of a complete site check out gatsby-theme-catalyst-hydrogen 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.

© 2020 Gatsby Theme Catalyst