Articles by Liana P

Migrating a blog from Jekyll to Gatsby with the jamstack

Liana P

Published on August 08, 2021

Moving on from Jekyll

I wanted to update my website which had previously been running on a Jekyll blog, and a custom old php website for the portfolio. In my research I found about the JAMstack design philosophy, which is about building static websites for super fast performance.

My Jekyll website was already built statically, but Jekyll is very specific and limited in what it can do. It is also built in Ruby which isn’t necessarily as easy to customise as a normal website. Nowadays though, there are lots of new frameworks that allow us to combine the advantages of static rendering with React or Vue and other features of a fully-featured web stack.

Let’s journey into the Jamstack

Jamstack frameworks

Some of the frameworks I considered (you can find more on the jamstack website:

• next.js is a popular react framework for building websites with React which now has support for static rendering
• gatsby is another similar React-based framework but is specifically built just for static rendering, and includes great features out of the box like a GraphQL system for fetching and querying content
• nuxt is similar to next.js but built around vue.js. I was interested in this because I like using Vue

In the end I chose gatsby for the following reasons:

• It is specifically made for static rendering. I know that I am only making a personal website/blog and won’t need a more complex client/server app. Using a limited system that specialises in static website makes sense
• It has a lot of great plugins and starter templates
• It is built around a great content pipeline using graphql that lets you easily query content in various formats directly in your page components
• I wanted to get more React experience

The biggest advantage of using such frameworks instead of having a blog engine with Jekyll, is that I get an actual website that I can develop on. Having access to all of React’s features and being able to use JSX components in pages makes this way more flexible that Jekyll ever could be.

Migrating jekyll markdown to markdown Gatsby can understand

One issue I faced early on is that Jekyll markdown files are formatted slightly differently than Gatsby. The Jekyll files have their date in the file name, and don’t have much info in the frontmatter headers. Gatsby meanwhile extracts the date from frontmatter headers, and the slug from the file name.

I had about 30 posts to migrate and didn’t want to do this conversion work manually, so I wrote a very configurable CLI tool to convert them. It’s open source and easy to use.

I wrote the tool in Rust as a way to practice it a bit more.

How I actually used Gatsby

I started with the Blog starter template which sets up a basic blog with common features like RSS, basic SEO (using helmet) and Markdown for content writing

Gatsby also supports integrating with a CMS, but I decided at this stage I don’t need to bother with that and can just edit Markdown manually.

Further changes I made to this template include:

• Changing the JavaScript to TypeScript (Gatsby supports TypeScript out of the box, just rename the files)
• Migrating from remark markdown to mdx. Mdx supports including React components inside markdown posts, which can be very powerful. I actually opened a pull request in the migration documentation to add more info
• Adding theme-ui to style my blog more easily and consistently
• The Gatsby graphql codegen plugin generates a type file for all GraphQL queries, making it easy to type the props of your react page components
• The Gatsby reading time plugin which makes it possible to get the reading time of an article in the graphQL query to display on your blog.

The result of all of those things is the website you’re reading this on. I am pretty happy with the workflow as I’ve been able to keep my old Markdown post

Hosting

I am hosting the new website on Netlify which is a hosting platform pretty much built for the Jamstack with all the features you could need to host a static website. The workflow is very simple, you just connect your git repo and Netlify will deploy your website when you push.

It has a generous free tier and also supports lots of fancy features like specific separate deploys for branches, preview builds, analytics, serverless functions. It even has an identity to easily handle logins or admin features

It’s been great to use and I’ve had no issues with it.

Redirecting old posts

Because of changing the stack, some URLs changed. For example. Jekyll appended the category of an article to its slug, in the format [category]-[article-slug]. I didn’t particularly want to keep that and was also changing domain name while migrating my website so I wanted to set up redirects from the old articles to the new ones.

To get a list of articles to migrate, I simply went on the Internet archive to find the sitemap of my old website and get all the URLs that existed on it. This included all the articles but also the pages (my new website doesn’t have pagination at the moment). Then using some copy-pasting and regexes, I converted that into a json object where I could map each old URL to its new one.

Gatsby has a redirect system which I used with my json file.

Because I also host this website on Netlify, I added the Gatsby Netlify plugin which can generate the _redirects file that Netlify uses for redirections automatically.