The Catalyst series of themes and starters for GatsbyJS were designed to provide an opinionated set of integrated themes and starters that can be used to accelerate your next Gatsby project. The vision is for one "core" theme in which most dependencies and components are contained followed by progressively more styled and refined child themes and starters. These themes rely heavily on Theme-UI and MDX.
Catalyzing Start:
# create a new Gatsby site using the basic starter
gatsby new catalyst-basic https://github.com/ehowey/gatsby-starter-catalyst-basic
# change into your new directory
cd catalyst-basic
# launch the site
gatsby develop
Example sites built with Gatsby-Theme-Catalyst:
- www.erichowey.dev - Based on
gatsby-starter-catalyst-blog
, Github Repo - www.briannasharpe.com - Based on
gatsby-starter-catalyst-writer
, Github Repo
Theme | Demo | Description |
---|---|---|
gatsby-theme-catalyst-core |
gatsby-starter-catalyst-core | This acts as the core theme on which all other themes are based. It houses a basic site architecture and components along with most commonly needed dependencies. Think of this as the foundation of a home. |
gatsby-theme-catalyst-header-top |
gatsby-starter-catalyst-basic | This adds a simple header to the core theme which includes support for anchor links and smooth scrolling out of the box. Logo on the left, nav on the right. |
gatsby-theme-catalyst-header-side |
gatsby-starter-catalyst-blog | This adds a sidebar style header to the core theme which includes support for anchor links and smooth scrolling out of the box. Logo is stacked on top, then title, then nav. |
gatsby-theme-catalyst-footer |
gatsby-starter-catalyst-basic | This adds a very basic footer to the core theme. |
gatsby-theme-catalyst-blog |
gatsby-starter-catalyst-blog | This provides a basic plug-and-play blog for any Catalyst based site. |
gatsby-theme-catalyst-writer |
gatsby-starter-catalyst-writer | This is the first complete site using the catalyst set of themes. Designed to be used by a freelance writer as their portfolio. Sanity is used as a CMS. |
Accessibility is important to me. I have made every effort to address accessibility issues in these themes and starters but would love additional feedback and help with more advanced accessibility topics as I am sure there are things I missed. Currently this theme is scoring 100 in Google Lighthouse audit for accessibility and passing tests using cypress-axe.
This set of themes is developer focused and I assume you have a basic knowledge of the command line, GatsbyJS, web development, git, etc. If you are brand new check out the getting started docs for GatsbyJS.
Helpful Reading:
- An Introduction to Gatsby Theme Catalyst
- Gatsby Theme Docs
- Using yarn workspaces with Gatsby themes
- Theme-UI Docs
- MDX Docs
- Component Shadowing in Gatsby Themes
All of these themes are available on NPM but the easiest way to get started is via a gatsby-starter that includes the theme(s) already. Currently the following starters are available:
gatsby-starter-catalyst-core:
gatsby new catalyst-core https://github.com/ehowey/gatsby-starter-catalyst-core
gatsby-starter-catalyst-basic:
gatsby new catalyst-basic https://github.com/ehowey/gatsby-starter-catalyst-basic
gatsby-starter-catalyst-blog:
gatsby new catalyst-blog https://github.com/ehowey/gatsby-starter-catalyst-blog
gatsby-starter-catalyst-writer:
gatsby new catalyst-writer https://github.com/ehowey/gatsby-starter-catalyst-writer
There are a number of options for the core theme, blog theme, and writer theme that act as flags to control various aspects of the site appearance and function. Try experimenting with some of these to get a feel for how it changes the site.
Core theme:
Option | Values | Description |
---|---|---|
contentPath |
String | Defaults to "content/pages", determines where the pages are created from. |
assetPath |
String | Defaults to "content/assets", determines where the page assets like images are located. |
displaySiteLogo |
true or false | Defaults to true, controls whether the logo is displayed |
displaySiteLogoMobile |
true or false | Defaults to true, controls whether the logo is displayed at the mobile breakpoint |
displaySiteTitle |
true or false | Defaults to true, controls whether the site title is displayed |
displaySiteTitleMobile |
true or false | Defaults to true, controls whether the site title is displayed at the mobile breakpoint |
invertLogo |
true or false | Defaults to false, controls whether the logo is inverted when the mobile menu is open |
useStickyHeader |
true or false | Defaults to false, controls whether the header is sticky or static |
useSocialLinks |
true or false | Defaults to true, controls whether the social links are displayed or not |
useColorMode |
true or false | Defaults to true, controls whether the dark mode toggle is available. |
mobileMenuBreakpoint |
String value, e.g. "1024px" | Defaults to "768px", sets the breakpoint for displaying the mobile menu, works independent of other breakpoints set in ThemeUI |
isHeaderSideLeft |
true or false | Defaults to true, only effects `gatsby-theme-catalyst-header-side, controls whether the header is on the left or right |
footerContentLocation |
String value, "left", "right" or "center" | Defaults to "left", determines the location of the footer content. |
Blog theme:
Option | Values | Description |
---|---|---|
contentPath |
String | Defaults to "content/posts", determines where the posts are created from. |
assetPath |
String | Defaults to "content/assets", determines where the post assets like images are located. |
basePath |
String | Defaults to "/blog", determines the page location for the post list. |
excerptLength |
String | Defaults to "140", determines the length of the excerpt use for post summaries. |
Writer theme:
Option | Values | Description |
---|---|---|
sanityDataset | String | Defaults to "production", change to reflect the dataset name you are using in Sanity |
sanityProjectID | String | Required, Sanity project ID |
Theme options are set via the gatsby-config.js
file. Specifically the navigation menu, social links menu, author name, site title, etc. The starter sites come with some pre-configured options you can modify. Most of these are fairly standard and where possible I Have included inline comments in the starters to help explain if needed. The socialLinks
object and menuLinks
object are a bit more complicated to support easier theme customization via the config file.
The menuLinks
is fairly standard with the addition of one field, type
, which controls whether the menu link is rendered as a Gatsby Link component or an anchor link using react-scroll
. The options are internal
or anchor
.
Example Config:
menuLinks: [
{
name: `Page 1`,
link: `/page-1`,
type: `internal`, //internal or anchor
},
{
name: `Anchor 1`,
link: `#anchor-1`,
type: `anchor`, //internal or anchor
},
]
The socialLinks
in gatsby-config is a bit unique. You can specify a social media provider such as Twitter and also three different locations in the settings, header
, footer
, and all
which will locate the icons appropriately. It will work with most major social platforms and has a fallback for displaying the text if a logo isn't pre-configured.
Example Config:
socialLinks: [
{
name: `Email`,
link: `[email protected]`,
location: `footer`, //Options are "all", "header", "footer"
},
{
name: `Github`,
link: `https://www.github.com/ehowey`,
location: `all`, //Options are "all", "header", "footer"
},
{
name: `Twitter`,
link: `https://www.twitter.com/erchwy`,
location: `header`, //Options are "all", "header", "footer"
},
],
Read about using theme-ui to customize a theme
Theme-UI based design tokens are used throughout the Catalyst series of themes and starters as this is the suggested best practice when building Gatsby themes. The theme is based on the tailwind presets as this provides a good base set of standard spacings, sizings, etc. You will also see a reference to colors like baseColors.pink[5]
in the theme file, these basecolors can be found on the TailwindCSS docs.
The file you should modify to set design tokens is always located in the following location:
.
├── src
├── gatsby-theme-catalyst-core
├── theme.js
Try changing some colors in the file and see what happens!
Most major areas of the site are preconfigured to use variants. This allows you to more easily change css styles without having to shadow a whole file. The following variants are available to use:
variants.siteContainer
: Targets the containerfor the entire site contentvariants.main
: Targets the component in the site, useful for changing spacing between , , and areas.variants.contentContainer
: Targets the containerfor the content, useful for changing site margins/content size.variants.header
: Targets the root componentvariants.footer
: Targets the root componentvariants.siteLogo
: Targets the logo componentvariants.siteTitle
: Targets the root site title component, useful to change font size of the site title.variants.navLinkStyles
: Targets the container styles for the nav links in the header, useful to change the nav styles
Here is an example of changing the size of the site title using variants.
variants: {
siteTitle: {
fontSize: [4, null, null, 5, null],
},
},
To add a custom font you need to first add the font as a dependency in your starter site, for example:
yarn add typeface-raleway
Then at the top of src\gatsby-theme-catalyst-core\theme.js
file you will need to import the font and declare it, like this for Raleway:
import { tailwind } from "@theme-ui/preset-tailwind"
import "typeface-raleway"
export default {
...tailwind,
fonts: {
...tailwind.fonts,
body: '"Raleway", sans-serif',
},
}
A common change you will need to make is to the logo and logo size.
The logo is found by default in the src/content/assets
folder under the names catalyst-site-logo.png
. Change this file to reflect your branding. You can use other file extensions, e.g. .jpg but you cannot change the file name. It is queried by file name for those that know graphQL, not by relativePath. So it will work with catalyst-site-logo.jpg
but not with logo-main.jpg
.
The logo size is managed in the following location: src/gatsby-plugin-theme-ui/index.js
. In many cases the size of your logo will control the size of your navbar/header. There is also an option in the sizes file which can override the auto height inherited from content and specify a fixed height.
Try this in src/gatsby-theme-catalyst-core/components/theme.js
for a big logo:
sizes: {
...tailwind.sizes,
maxPageWidth: "1440px", // Sets the max width of elements like the header/footer on really large screens
maxContentWidth: "720px", // Sets the container size on larger screens, e.g. tablets and laptops
headerHeight: "auto", // Provides fallback setting to control header height
logoWidthXS: "80px", // Logo width on extra small screens, up to 480px
logoWidthS: "150px", // Logo width on small screens, 480px - 768px
logoWidthM: "150px", // Logo width on medium screens, 768px - 1024px
logoWidthL: "260px", // Logo width on large screens, 1024px - 1440px
logoWidthXL: "260px", // Logo width on extra large screens, above 1440px
logoHeightXS: "80px", // Logo height on extra small screens, up to 480px
logoHeightS: "150px", // Logo height on small screens, 480px - 768px
logoHeightM: "150px", // Logo height on medium screens, 768px - 1024px
logoHeightL: "260px", // Logo height on large screens, 1024px - 1440px
logoHeightXL: "260px", // Logo height on extra large screens, above 1440px
iconsFooter: "32px", // Sets the icons size for the footer
iconsHeader: "20px", // Sets the icons size for the header
},
This file is used as the default image in places like Twitter and Facebook. This file is best in a 2:1 aspect ratio, something like 1200x600px. See the twitter card docs for more information. You can use alternate image types such as .jpg if you want. It is queried by file name for those that know graphQL, not by relativePath. So it will work with catalyst-social.jpg
but not with social-image.jpg
.
There is also a file called catalyst-site-icon.png
that provides your icon for use gatsby-plugin-manifest
to create icons for web, PWA, etc. This file should be square and at least 512x512px in dimensions.
There are three context providers that are globally available in the themes to manage component function or appearance based on state. These are isHome
, isMobile
, and isNavOpen
.
isHome: True if you are at the root of your site
isMobile: True if the viewport width is smaller than the value set in mobileBreakpoint
option via theme options
isNavOpen: True if the mobile nav menu is open
// Import useContext and the context
/** @jsx jsx */
import { jsx } from "theme-ui"
import { useContext } from "react"
import { MobileContext } from "gatsby-theme-catalyst-core"
const Example = () => {
// Access the context in your component
const [isMobile] = useContext(MobileContext)
// Conditionally change css or render components
return (
<div
sx={{
height: "200px",
width: "200px",
backgroundColor: isMobile ? "red" : "blue",
}}
>
{isMobile && <Component />}
</div>
)
}
export default Example
By default Gatsby provides excellent SEO out of the box. I have extended this with a custom SEO component based on gatsby-plugin-react-helmet that provides basic open graph and metadata tags. It also provides a default social sharing image based on catalyst-site-social.png
. The blog theme has a "featuredImage" field in the frontmatter which replaces the default social image. If a twitter profile is included in the socialLinks
field in gatsby-config.js
it automatically generates the correct metadata tags based on your profile.
The first place to start is by checking the changelog file. Beginning at release v0.20.0 I have started tracking major changes in there. Other major breaking changes will be commented on here.
gatsby-theme-catalyst-header-basic -> gatsby-theme-catalyst-header-top
I renamed this theme to better reflect what it is. The only change you should need to make is in your gatsby-config.js file and package.json.
gatsby-theme-catalyst-footer-basic -> gatsby-theme-catalyst-footer
I renamed this theme to better reflect what it is. The only change you should need to make is in your gatsby-config.js file and package.json.
Simple Core Theme
gatsby-theme-catalyst-core
was designed and built to be as simple and unstyled as possible. A barebones starting point which can be easily maintained in the future to manage dependencies on client sites.
Child themes to extend the core theme
These child-themes are focused on extending function and remain as design-agnostic as possible. Again this makes longterm maintenance easier for client sites. It is my preference to begin new projects without too much styling that has to be undone.
Starter sites to extend and style the themes
The starter sites provide a "quick start" for site development using the themes as dependencies. Currently the starter sites only provide basic implementation of the themes. It is my vision however that in time there could be more styled and complex starters released which do not need as much customization and include more rigid styling.
This is a passion project for me. I would love any additional feedback, suggestions and pull requests. I can be contacted via email at: [email protected]
I would like to acknowledge all of the help I have gotten in working on this project from people answering questions on the GatsbyJS issues, Chris Biscardi's blog, and the work that @4lpine and @jxnblk have done documenting Theme-ui so well.