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.
Install the theme using a starter
# create a new Gatsby site using the starter sitegatsby new lithium https://github.com/ehowey/gatsby-starter-catalyst-lithium
Develop your site for the first time
# switch to the lithium directorycd lithium# run gatsby develop for the first timegatsby 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.
The menuLinks
array is common in Gatsby sites with the addition of one field, type
, which controls whether the menu link is rendered as a Gatsby Link component or an anchor link component using react-scroll. The options are internal
or anchor
. Submenus are only supported on internal links at this time.
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},]
You can also have a sub-menu or dropdown menu.
Example Config:
menuLinks: [{name: `Page 1`,link: `/page-1`,type: `internal`, //internal or anchorsubMenu: [{name: `Sub 1`,link: `/sub-1`,type: `internal`, //internal or anchor},{name: `Sub 2`,link: `/sub-2`,type: `internal`, //internal or anchor},],},]
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.
A more advanced way to change the logo is through component shadowing which gives you greater control over the logo and file naming. The file you need to shadow is
gatsby-theme-catalyst-header-top/components/branding/branding-logo.js
.
The logo size is managed via the Theme-UI theme file. You can set appropriate sizes for your logo there.
Try this in src/gatsby-plugin-theme-ui/index.js
for a bigger logo:
sizes: {...tailwind.sizes,maxPageWidth: "1440px", // Sets the max width of elements like the header/footer on really large screensmaxContentWidth: "720px", // Sets the container size on larger screens, e.g. tablets and laptopsheaderHeight: "auto", // Provides fallback setting to control header heightlogoWidthXS: "80px", // Logo width on extra small screens, up to 480pxlogoWidthS: "150px", // Logo width on small screens, 480px - 768pxlogoWidthM: "150px", // Logo width on medium screens, 768px - 1024pxlogoWidthL: "260px", // Logo width on large screens, 1024px - 1440pxlogoWidthXL: "260px", // Logo width on extra large screens, above 1440pxlogoHeightXS: "80px", // Logo height on extra small screens, up to 480pxlogoHeightS: "150px", // Logo height on small screens, 480px - 768pxlogoHeightM: "150px", // Logo height on medium screens, 768px - 1024pxlogoHeightL: "260px", // Logo height on large screens, 1024px - 1440pxlogoHeightXL: "260px", // Logo height on extra large screens, above 1440pxiconsFooter: "32px", // Sets the icons size for the footericonsHeader: "20px", // Sets the icons size for the header},
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 themeremarkImagesWidth: 1920,displaySiteLogo: false,displaySiteLogoMobile: false,// Blog themeexcerptLength: 140,basePath: "/writing",// Lithium themeuseHero: 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 Styled 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 onlineexperiences 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:
<Buttonas={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.
Use variants to change the site title
Variants are used throughout the theme to allow for easier visual customization without having to shadow an entire component. Variants are modified via the Theme-UI theme file and if you scroll to the bottom of the existing file you can see some examples of those variants. There is a full list of available variants in the theme docs.
Let’s use variants to make a simple change to the appearance of the site title:
variants: {siteTitle: {textTransform: "uppercase",color: "primary", // this is keyed to the 'primary' color in the themefontSize: [3, 4, null, 5, null],"::after": {content: "none",},},// ...more variants}
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 postdate: 2020-07-01categories: [Coding]featuredImage: ../assets/garden-3.jpgsocialImage: ../assets/lithium-social.jpgfeaturedImageCaption: Photo by Markus Spiske---# My first postI 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!