Upgrading to Blog Theme 2.0

July 08, 2020

A few months back I launched my self-hosted blog on this site with a post on the process. I ended that post discussing the points of friction in using gatsby-theme-blog and vowed to work with the Themes Team to improve some of the rough edges.

As it turns out, some things changed between then and now. Most significantly I joined the themes team and decided to roll up my sleeves and solve these challenges myself!

Despite writing the code, updating the docs and producing a blog post for the release on gatsbyjs.org I figured one more post couldn’t hurt.

The focus here is on how I migrated this site and specifically addressed the notes from my initial experience.

Upgrading

I won’t spend too much time on this because it’s written elsewhere. Specifically, the migration notes in the README.

Styles

To be perfectly transparent I didn’t really follow my own advice. I upgraded to 2.0 despite not wanting to change the look of my blog. That meant re-implementing typography. However, I look forward to the flexibility that gives me for a re-design going forward.

I also opted to continue using the default preset styles with my minimal overrides. I’d figured out how to work with them in a way I enjoyed. But it’s nice to know that I now have the option to turn them off.

{
resolve: `gatsby-theme-blog`,
options: {
basePath: `/posts`,
preset: false
},
},

Accessibility

The most significant piece of the migration was working with the new SkipNav feature. Thanks to awesome work by the larger Gatsby Team gatsby-theme-blog now includes a major accessibility feature for navigation. It’s built into the layout of each post and the header.

In my case, I override the header of each blog post and my blog sits in a larger site outside of the theme. That meant adding SkipNav manually in addition to what the theme shipped. There is a great example repo from Madalyn that shows how to do this.

Adding Features

Images

With a working site I was able to make use of all the new features! The big one was featured images that also act as social images. This post is using a local image file, but I could make use of an external URL which is pretty cool.

Prism

One of the other points of friction was wanting to use a prism preset without having to design my own. Lucky for me, it’s now built it in!

{
resolve: `gatsby-theme-blog`,
options: {
basePath: `/posts`,
prismPreset: `prism-okaidia`
},
},

The other nice Prism feature is actually highlighted (get it!) above. The theme now supports line highlighting in code snippets! Really excited to use this moving forward.

What’s Next?

Last time I talked about the points of friction and things I wanted to see. I’m pretty excited by what we’ve done so I’m looking forward to getting input from other voices.

In the process of releasing this we’ve written A LOT of docs. I look forward to watching everyone play around with the Blog Theme and make it their own.


A blog by Laurie Barth.
Teacher of all things tech.