Creating a blog with gatsby-theme-catalyst-lithium

This tutorial will walk you through setting up a personal blog using gatsby-theme-catayst-lithium.

I assume you have some basic familiarity with Gatsby and web development in general. If you are brand new to Gatsby I would suggest beginning with their excellent tutorial and coming back here later.

This tutorial could also be followed for gatsby-theme-catalyst-helium which is very similar with only minor differences.

Install the theme using a starter

# create a new Gatsby site using the starter site
gatsby new lithium https://github.com/ehowey/gatsby-starter-catalyst-lithium

Develop your site for the first time

# switch to the lithium directory
cd lithium
# run gatsby develop for the first time
gatsby develop

You should now be viewing a demo site with some placeholder content!

Now let’s personalize it and make it your own.

Update gatsby-config.js

gatsby-config.js is the command centre for your website - update the site title, description, keywords, social links, etc. There are inline comments in the file which should be helpful, however the menuLinks and socialLinks fields are more complex and worth a quick review.

Example Config:

menuLinks: [
  {
    name: `Page 1`,
    link: `/page-1`,
  },
  {
    name: `Page 2`,
    link: `/page-2`,
    subMenu: [
      {
        name: `Sub 1`,
        link: `/sub-1`,
      },
      {
        name: `Sub 2`,
        link: `/sub-2`,
      },
    ],
  },
  {
    name: `Anchor 1`,
    link: `/#anchor-1`,
  },
]

The socialLinks array allows you to customize the social media icons displayed on your site. Three different locations are supported, header, footer, and all. It will work automatically with most major social media platforms and has a fallback for displaying text if a logo isn’t found. You can also remove this entirely via the theme option, useSocialLinks.

Example Config:

socialLinks: [
      {
        name: `Email`,
        link: `eric@erichowey.dev`,
        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"
      },
    ],

Customize the Theme-UI theme

Theme-UI is used to manage all aspects of the visual design, from colors, to fonts, to spacings and more. The theme file is always located at src/gatsby-plugin-theme-ui/index.js. Try playing around with some of the colors and values in the file to change the appearance of your site. You can read more in the docs about the use of Theme-UI in Gatsby Theme Catalyst.

Change the logo and site icon

The logo and icon are found by default in the src/content/assets folder under the file names catalyst-site-logo.png and catalyst-site-icon.png. Overwrite these files to reflect your branding.

The logo is queried by file name, you can use a different file type, e.g. jpg, but the name must be catalyst-site-logo. The site icon is referenced in gatsby-plugin-manifest and automatically creates all the needed icons for your site and should be at least 512px x 512px.

Open up src/components/header/branding.js and take a look around, it is well commented and you can modify the logo size, font sizes, etc. all in this file which is actually using component shadowing.

Adjust theme options

Gatsby Theme Catalyst makes wide use of theme options to manage aspects of your site from design to feature flags. For example there are options to manage whether logos are displayed or not, to set the content paths, and more. You can review all of the available options in the main docs page for gatsby-theme-catalyst-lithium.

For example let’s say you wanted to change the base path for you blog to www.yourdomain.com/writing, disable the hero section, and remove the ugly logo entirely.

{
  resolve: `gatsby-theme-catalyst-lithium`,
  options: {
    // Core theme
    remarkImagesWidth: 1920,
    displaySiteLogo: false,
    displaySiteLogoMobile: false,
    // Blog theme
    excerptLength: 140,
    basePath: "/writing",
    // Lithium theme
    useHero: false,
  },
},

Customize the hero component

The hero component is found at src/gatsby-theme-catalyst-lithium/components/hero.js and is an example of component shadowing. This component is styled using Theme-UI, and more specifically the Themed component and the sx prop.

To customize this hero component you have two options; erase what is there entirely and start from scratch or modify the existing hero component. In this tutorial we will cover modifying the existing hero component.

The image for the hero component is located at content/assets/hero-image.png. To change the image you can overwrite this file.

The text content is all contained is this part of the code:

<Styled.p sx={{ fontSize: [3, null, null, null, 4] }}>
  I grow vegetables, flowers and community. I build remarkable online
  experiences focused on{" "}
  {hasMounted ? (
    <Fragment>
      <RoughNotation type="underline" show={true} strokeWidth={2}>
        connection
      </RoughNotation>
      <span> and </span>
      <RoughNotation type="underline" show={true} strokeWidth={2}>
        belonging.
      </RoughNotation>
    </Fragment>
  ) : (
    "connection and belonging."
  )}
</Styled.p>

You can erase everything between the <Styled.p> tags and write whatever you want here.

There are some special things happening worth mentioning if you want to keep the handwritten underline effect. This effect is created by Rough Notation and it relies on the document window which means this code has to be conditionally loaded after the component has mounted. There is also fallback text provided that is rendered immediately on browser load to ensure the text remains visible the entire time.

Right below the paragraph tags is the code for the button, you can change the Grow With Me text to whatever you want:

<Button
  as={Link}
  to="/contact"
  sx={{
    bg: "#2b6cb0",
    fontSize: [2, null, null, null, 3],
    transition: "all 0.3s ease-in-out",
    ":hover": {
      bg: darken("#2b6cb0", 0.08),
    },
  }}
>
  Grow With Me
</Button>

You now have your very own custom hero section.

Add a new blog post

Time to start adding some content! By default posts are located at content/posts. The theme is set up so posts are authored in MDX or plain markdown.

Here is an example post with the required frontmatter:

---
title: My first post
date: 2020-07-01
categories: [Coding]
featuredImage: ../assets/garden-3.jpg
socialImage: ../assets/lithium-social.jpg
featuredImageCaption: Photo by Markus Spiske
---

# My first post

I am a great writer!

Launch it

Once you are happy with your final design and have some content it is time to push the big launch button! You can deploy this site to your host of choice and Gatsby, as usual, has some great docs on deployment and hosting.

Feel free to send me an email or a tweet if you have questions, comments or get stuck! I would love to see what you create!