Skip to content

Getting Started

This guide assumes the following:

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

Install the themes using a starter

This guide uses a barebones starter which is designed as a boilerplate for further development and customization. It includes a minimal set of styles, utility components and core functionality like a mobile navigation menu. Content is authored in MDX.

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 better way of doing this with React suspense.

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 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,
//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 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