Introduction to Gatsby Theme Catalyst
Eric Howey • January 01, 2020
Gatsby Theme Catalyst is my opinionated view of a modern tech stack relying on a combination of Gatsby, MDX, and Theme-UI. I built this series of themes to accelerate the development process and have a modular approach for my freelance work. As a side benefit building this project has been a great way to learn exciting new technologies including React and GraphQL. The themes are all open source, managed in a monorepo, and I have done my best to provide robust documentation on github. Contributions are welcome and encouraged. If you have a suggestion or run into a problem please submit an issue on Github.
How it works?
Imagine Lego. A set of interlocking blocks that connect together to create a final form.
It all starts with a solid core theme. This acts as a base layer for other themes providing package dependencies, hooks, SEO, initial plugin configurations and more.
You then pick additional themes as necessary such as a header theme and footer theme to match your site design. This provides a basic, unstyled, starting point for building a custom site. Change the colours, add branding, add content, shadow components and you are ready to go. For an example of this in action see gatsby-starter-catalyst-basic and this site which is a styled version of the basic starter.
There are also more “complete” themes with CMS integration, custom components, and styling. These themes require less customization before being ready to go - but are also less flexible because of how tightly integrated they are. For an example of this in action you can see gatsby-starter-catalyst-writer and briannasharpe.com, which is a customized version of the starter.
Currently there a limited number of themes and starters however I will be adding more and focusing on enhancements now that the core API and base themes are stable.
This will walk you through a setup for a basic blog using Gatsby Theme Catalyst. I assume you have a development environment already setup for Gatsby and some familiarity with Gatsby in general. If you are completely new to Gatsby I would suggest starting with the official tutorial first.
Use gatsby-starter-catalyst-blog for an initial setup
This starter implements four themes,
gatsby-starter-catalyst-blog. It is purposefully unstyled to give a clean starting point for building a custom Gatsby based blog.
# create a new Gatsby site using the catalyst basic starter sitegatsby new catalyst-blog https://github.com/ehowey/gatsby-starter-catalyst-blog# change to your new directorycd catalyst-blog# run gatsby develop for the first timegatsby develop
You should now have something that looks like this:
Customize your siteMetadata, socialLinks, logo, theme colors and more
You can now configure a whole host of options via
gatsby-config.js including your site title, social links, menu links, etc. There is documentation about the options for this on Github.
You can change colors, fonts, spacings and more via
src/gatsby-theme-catalyst-core/theme.js, again there is more detail on how to do this in the docs on github and via Theme-UI’s excellent docs.
The logo can be changed by replacing
content/assets/catalyst-site-logo.png. This can be a .jpg file as well but the name needs to remain
catalyst-site-logo for the query to work. You could also shadow the entire logo component for more granular control but that is a more advanced solution.
Add some of your own content
Create a new file in your posts directory like this,
Add the following information to the file and save it.
---title: My new postauthor: My nameauthorLink: https://twitter.comdate: 2020-01-05featuredImage: ../assets/featured1.jpgdraft: false---Here is my awesome new post
Congratulations you have just started your first blog post! You can find information on additional supported frontmatter fields in the docs.