My Gatsby setup

Gatsby is a framework which employs React to build sites just like the one you see here. There’s quite a few parts to it, so I’ll go over the setup in this post, and the things that I’ve added to make the experience pleasant, both for users (to read and explore) and myself (to work on and iterate).

Base styles and components

While there’s a few ways of setting up styles on the site, I have 2 primary methods of styling:

• A global CSS file which contains styling which is common across components.
• CSS-in-JS, styles in components that are specific to individual components, such as layout, header, buttons.

Having tried both, it does feel a bit easier to separate concerns with styling—it’s a lot more difficult to have collisions with class naming. There’s an endless debate as to whether CSS-in-JS is the right approach or not, but that’s another article for another time.

As for the components themselves, they’re mostly straightforward to work with. Below is a sample from my DateTime component which is used in the articles section:

// file: src/components/datetime.js
import React from "react"

const DateTime = props => (
  <p>
    <time datetime={props.datetime}>{props.dateformatted}</time>
  </p>
)

export default DateTime

This can then be used by other components like so:

// file: src/components/recent_posts.js
...
const RecentPosts = () => {
  return (
    ...
    <DateTime datetime={node.frontmatter.htmldate} dateformatted={node.frontmatter.date} />
    ...
  )
}

export default RecentPosts

I’m sure I could make even better use of React, but the fact is that I don’t think I have that bigger picture just yet. Maybe I’ll make it possible to have a dark-mode toggle switch or something. One day.

Article rendering

Articles use gatsby-transformer-remark, which provides the ability to parse markdown files, and it exposes a way for additional plugins to do their thing.

I use the gatsby-remark-smartypants plugin to modify the output a little, including directional quotes, em-dashes, ellipses—things that make the reading experience a bit more pleasant.

Code blocks use gatsby-remark-prismjs, enabling syntax highlighting for code blocks like you see above. It has a variety of themes—I’ve opted to use a11y Dark for code blocks, due to the fact that it:

• Looks nice—the colours help distinguish between different bits of code.
• Contrasts nicely with the text blocks that go around it.

Images use gatsby-remark-images with the tracedSVG option so it’s possible to show a SVG placeholder, and then lazy load in images when the user scrolls it into view.

Typography

gatsby-plugin-typography provides Typography.js an easy way to define font choices and sizes, which are used for headings and content. I use Lato for the header fonts, as it became part of my branding and I thought it suitable here.

Literata was used for the main content, as I encountered it in the Android app of Google Play Books and I found it very easy to read.

Other things

Because this is a static generated site, we have to fit in a few more things which would normally be done by the CMS templating engine into the build:

• gatsby-plugin-manifest: Creates a manifest file for progressive web app (PWA) support, used in conjunction with gatsby-plugin-offline.
• gatsby-plugin-robots-txt: Generate a robots.txt at build—I’ve configured it to indicate the presence of the sitemap.xml file which is generated by gatsby-plugin-sitemap.
• gatsby-plugin-feed: Provides support to subscribe to a RSS feed containing all my written articles.

Closing thoughts

Is it over-engineered? Perhaps—at the end of the day, I’m just using text files to produce and publish HTML pages.

However, it is a valuable learning experiment to play around and tinker, and I’m still learning things as I go.