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.
Gatsby had some instant appeal to me; it could be installed using
I specifically used the Gatsy Material Starter as the design out the box was solid and I am a big fan of Material Design. The default layout is the foundation of this site.
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 : Gatsy Date Fields Are Just Strings
The date field in the frontmatter in Jeyll 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 mean all of my old posts rendered with an ugly date string, not something formatted consistently.
Here is the sample frontmatter used for this article;
title: Using Gatsby As A Blogging Tool tags: [reactjs, js, gatsby] date: 2018-02-01 @ 15:40 category: "js" cover: /gatsby.jpg
Pain #2 :Preserving Order
Now obviously people prefer to keep their articles in chronological order, but its 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 posts 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, and 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 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;
npm run build s3-deploy
That gives you the site you have here, and I no longer need to bother with any Ruby dependencies for this site. Happy days.