Using Gatsby As A Blogging Tool

The old version of this website was built using Jekyll. Jekyll is a popular static website generator which uses Ruby to parse markdown/HTML files into static HTML. Jekyll allowed writers to focus on the writing not the interface of the CMS, you could write an article in any text editor, and by using the common markdown frontmatter tags it could give similar results to the output of a dynamic CMS (tagged articles, related categories, etc.) without needing a database. This static site Jekyll generated could be cheaply hosted on GitHub Pages or Amazon S3, and as a result Jekyll quickly became the de-facto tool for small tech blogs and GitHub community sites.

Having used Jekyll for a couple of years I was quite happy with the overall result - it gave me a well-themed blog, through which I could write articles about technical topics I found interesting.

Over the years though, my projects have mostly moved to the JavaScript stack; likely through the typical framework path many other Developers will have experienced; Backbone, then Angular (1.x) and now React with some React-Native thrown in for good measure.

My intention was to quickly port the Jekyll site content to a new JavaScript-based generator framework I found called Gatsby.

Gatsby had some instant appeal to me; it could be installed using NPM/Yarn, and everything is written in JavaScript. Gatsby renders everything as a React Component, and that keeps enough separation of concerns, without me needing to learn yet another CMS framework.

I specifically used the Gatsy Material Starter as the design out of the box was solid and I am a big fan of Material Design. The default layout is the foundation of this site.

Migration

My old Jekyll site used markdown, so all I had to do was remove the redundant frontmatter fields (layout, etc) and add in cover and category properties.

There were a few areas of pain though;

Pain #1: Gatsby Date Fields Are Just Strings

The date field in the frontmatter in Jekyll uses a full timestamp which the commonly-partnered Octopress post generator uses, which saves a bit of boilerplate process. The date field in the Gatsby frontmatter however does not parse dates as a datetime, and instead just treats it as an arbitrary string – which means all of my old posts are rendered with an ugly date string, not something formatted consistently.

Here is the sample frontmatter used for this article;

Pain #2: Preserving Order

Now obviously people prefer to keep their articles in chronological order, but it's important to note (again) that although the date field is used, it is treated as a string for sorting – note a date sort – so make sure your dates are stored in the YYYY-MM-DD format.

I ultimately settled with each post being located in its own folder which matches the .md filename, and using the YYYY-MM-DD-lowercase-title-here naming pattern for both. I also found this was a clean way to group my cover image assets, as local cover images could be referenced with a relative path in the markdown file (Just make sure the path starts / so the conditional can fire).

These considerations kept posts in the same order in my IDE, file system and Gatsby.

Pain #3 : Quirky Caching

I went through two clean installs of Gatsby before I realised there was a fairly frequent compilation issue on OSX, that an invalid frontmatter format could be cached, and even if the file was corrected, the only way to fix the broken compilation step was a total deletion of the .cache folder in the root.

However, once the above issues were observed and considered, the process has become pretty painless and porting over all the articles took about 20 minutes.

Deployment To AWS S3

I used the s3_website plugin to deploy my Jekyll site to S3 in the past and again, as with Jekyll it worked really rather well. The aim of this whole process was to consolidate around JavaScript, so I looked for a Node alternative and I settled on s3-deploy.

I found the quickest way to get it working (Once the .env file was created) was to delete the contents of my target AWS bucket and then on my machine run the s3-deploy create command and amend the generated .s3-website.json file. I only needed to change the bucket and region name to the ones used previously. Also, remember to use public as the uploadDir value so you deploy the generated site only.

Now to deploy new posts I just follow a simple chain of;

That gives you the site you have here, and I no longer need to bother with any Ruby dependencies for this site. Happy days.