From Pelican to Gatsby, and why?

This blog of mine has been a static site for almost its full lifetime. In short, a static site is built beforehand, and is served to users’ browsers from the server as prerendered html for the content, css for styling, JavaScript for client-side functionality and some assets such as images and font files.

A static website requires just a basic web server to serve the assets to clients. Since there is no server-side logic or processing, static sites are typically blazing fast and secure against many common security threats. This is because there is practically next to nothing to attack against. Quite a bit better and stronger setup than a dynamic website, such as a WordPress site, which needs a database and PHP installed on the server. Plenty of opportunities to get things wrong by misconfiguration and absent security updates.

Static site should be the first choice, unless something specifically requires something else, because of simplicity and security to begin with.

The previous setup and publishing process

For a couple of years, this site was built with a Python-based static site generator called Pelican. It was a perfect fit for my needs at that time; written and extendable in Python, with capabilities for custom theming and full automation for publishing. It goes without saying, that the content is written in markdown, since that is the way I write everything.

The site was hosted on AWS S3 bucket, and served through CloudFront distribution to enable https and gain some speed for North American readers, where most of my readers are coming from. The TLS certificate was obtained through AWS Certificate Manager, and automatically renewed.

The build and publishing workflow was quite straight forward:

  • Write the article in markdown on my laptop or iPad.
  • Build the static content by running the build script on my laptop.
  • The build script also fixed some issues caused by a couple of Pelican's plugins.
  • Run a separate shell script, which pushed the assets to S3 bucket, while deleting the old assets from the bucket. After pushing the new content, the same script initiated an invalidation of CloudFront distribution's cache, which automatically launched the rebuilding of the cache on CloudFront.
  • The new version of my site was now publicly available.
  • As a last step, I pushed the new source code to git manually.

Not too bad, overall. Then again, things could be better. The whole build process could be automated, requiring only pushing new code to git. Based on the git branch, the result could be either a staging version or a production version of the site.

In addition, over the years my setup become quite bloated with various doodads, to fix some issue or add some functionality. It felt, that is was time to start from scratch.

Rebuild and conversion

After looking into and trying out various static site generators in either Python (very few good options) or JavaScript (plenty of good options), the one, that seemed to get only positive comments, was Gatsby. Gatsby is based on React and relies heavily on GraphQL for data fetching, though other options are available. There are vast amount of plugins for numerous needs, such as handling markdown and images, or generating sitemap.

Since I was already using React for practically all frontend development that I do, the choice become a no-brainer. After some YouTube video intros, a short intro course from Scott Tolinski (Level Up Tuts), and tinkering with Gatsby I felt strong with this one.

Both my old and new setups are based on markdown, so almost all of my content was good to go. When it comes to the frontmatter of the said markdown files, I had to regenerate them to fit the new build process. That was a semi-automated process; just read the old markdown in, read the frontmatter, generate new frontmatter and paste the markdown as is, and save new file. Python makes tasks like these so easy, that it also feels like cheating.

I also looked into the alternatives for hosting my site, not that there was anything wrong with the old one. Since I had already used Netlify on a couple of React SPA projects to host the frontend code, I wanted to try Netlify for my own site too. Netlify also issues a free TLS certificate via Let’s Encrypt.

The current setup and publishing process

The current build process is as follows:

  • Write the article in markdown either on my laptop or on my iPad.
  • Optional step: If I'm on my laptop, I will build the site locally and test that everything works.
  • Push the code to git, hosted on GitLab. I use the SaaS option available on gitlab.com, GitHub would work just as well on this use case.
  • Netlify kicks off the build right after I push the code, and publishes a new version of the site based on the git branch, either to staging or to production.
  • Both GitLab and Netlify will notify me on Slack on the various steps, as the process progresses.

So, in short, I fixed the things I wanted to have in my previous setup.

Overall, the process of learning Gatsby and rebuilding my own site from scratch, was a pleasant and refresing experience. The learning curve was not too steep, because I already knew enough React. I wasn't too confident with GraphQL, but this was a great opportunity to extend my knowledge and improve my skills.

What’s next

There are plenty of opportunities to extend the functionality of the site within the Gatsby ecosystem. Regardless of that, my goal is to write a bit more than I have done in the past couple of months.

Further reading