Switching from Hugo to Gatsby

December 1st, 2019

Past static site generators

For the past year & a half, I've used to static site generator Hugo. Hugo is written in Golang and ships a single binary - which makes it super easy to install! It's also pretty fast when it comes to rendering the site (typically under ~1 second). This all sounds great right?

The main issue I have with Hugo is the lack of extensionability (through plugins) and the templating language used.

Before Hugo, I used the Jekyll static site generator (written in Ruby) that comes with a fairly decent plugin ecosystem.

The other issue I had was the templating language Hugo used. Golang ships with a native package for dealing with templating text/template which is what Hugo using at it's core. It also has some extra functionality that extends the templating syntax (such as shortcodes).

While the templating language is full featured and certainly does what it needs to, writing anything in it was never a pleasant experience.

A New Year, a New Site

Because I'm always trying to improve my personal site, I upgrade the design every year or two.

With the new site design, it felt it would also be a good time to try and find a static site generator that fit my needs better than Hugo did.

Lately I've been writing more & more React (an ES6 SPA framework), so I looked into static site generators that would let me write React components to build my site. Enter Gatsby.js, a static site generator that does exactly that.

Using Gatsby, you build the site using components rather than a templating language like Liquid (Jekyll) or the built in templating language (Golang/Hugo).

For example, the header component might look like this

const Header = () => (
    <div className='header'>
        <ul>
            <li>Home</li>
            <li>Blog</li>
            <li>About</li>
        </ul>
    </div>
)

The site render time for Gatsby is slower than Gatsby but still within reason (at least so far).

Another benefit of using Gatsby is Mdx, which is Markdown + React Components.

Cheatsheets & Mdx

A big feature I wanted to incorporate with my new design is cheatsheets. Basically helpful little guides on how to do certain things (such as common React proptypes or the basic syntax for Golang).

It's essentially a public wiki for things I use often but not often enough to remember.

Devhints.io is a site that I've used in the past whose design seems to work very well for the type of wiki I'd like however it uses a feature of Jekyll called block level attributes to add css classes to style things within the markdown itself.

Most markdown parsers don't implement this feature but Mdx is allows me to do something similar using custom shortcodes (components). For example, to specify a section of code as the 'setup' portion of a section, I can wrap it using a <CodeSetup> component for example

<CodeSetup>
// markdown goes here
</CodeSetup>

The only issue I have with Mdx is that it's super finicky when it comes to parsing markdown within components

In the following example, the content within the <CodeSetup> component would not be rendered as markdown:

<CodeSetup>
## Hello
</CodeSetup>

But if we add an empty line between the markdown and the <CodeSetup> component tags, it will get rendered as Markdown.

<CodeSetup>

## Hello

</CodeSetup>

It's an annoying issue but one that I can still work past.

A recap & future optimizations

So far I've been way happier with Gatsby compared to Hugo. I've always enjoyed writing things in React so it makes sense to use the same framework for my own site.

The next steps for my site is to optimize the hell out of it. My previous site design using Hugo loaded in under half a second so I'd like to reach comparable or even better times using Gatsby.