New Website

October 05, 2020

So 2020 has been an interesting year for myself, and I am sure all of you as well. With the majority of everyone working from home, myself included. I have found new pockets of time that were not being spent on commuting. As such I have been able to leverage this new-found time to tackle one of the long-standing projects on my list. A personal blog/website!

Requirements

To start things off, lets talk about how I ended up here. My primary goal was to have a platform for blogging, but also facilitate functionality beyond that. Secondly, I was looking to leverage one of the many static website hosting services. Lastly, I wanted the platform to be something that I could modify extensively to my own liking.

For my first requirement I had considered content publishing platforms such as Medium or WordPress. Which are great on their own and do not require me to worry about hosting. The main pain point was they lacked the level of customization that I was looking for in a platform. While WordPress does offer lots customization and even static site generation, it carries a lot of bulk compared to other static site generators.

Static Site Generators

With my requirements in mind, I then began to shop out static site generators. There is wide variety of these tools available and in almost every programing language. With some of the more popular ones being Gatsby, Hugo, and Jekyll. To not get stuck in choice paralysis, I would have to revise my requirements. Time to break down my top three choices.

Jekyll is the most mature project on this list and the most familiar. It is simple and has been powering GitHub Pages for years. It has simple page generation and templating, as well as simple blogging support.

Hugo touts itself as “The world’s fastest framework for building websites” and has come highly recommend by my former colleague Josh. It has quite a few more features compared Jekyll, such as i18n and image processing.

Gatsby has to be one of the most interesting static site generators that I have seen. It deviates from the standard content and template model used by the vast majority of other generators, instead acting as an ETL framework. In addition, it integrates React to create an optimized SPA experience.

The Decision and Build

I finalized my choice and picked Gatsby as my static site generator. As it easily fulfilled my three primary requirements. With it more than exceeding my expectations for the third requirement by additionally offering support for SSR if I should need it in the future.

Now with the site framework chosen it was time to take care of the design details and decide if I would be using any sort of CSS framework. After reaching out to another colleague, Dylan recommended I use Tailwind CSS. It is a utility-first CSS framework that changes the paradigm used by a lot of other CSS frameworks. Its utility class approach generates most everything you need and leverages PostCSS to remove everything that was not used. I have also observed instances of the framework popping up in the wild such as the GitHub CLI website.

From my first impressions, I really enjoy having the classes available without having to manage all my CSS selectors. It allows me to easily reuse and compose my styling, while cutting down duplicate styling rules throughout the site. Down bellow is an excerpt from the homepage showing how utility classes work.

<div className="m-auto w-full bg-gray-50 bg-opacity-75 p-4 shadow-lg sm:w-auto sm:max-w-3xl sm:rounded-lg sm:p-6">
  <div className="text-center">
    <h2 className="text-4xl font-extrabold leading-10 tracking-tight text-gray-900 sm:text-5xl sm:leading-none md:text-6xl">
      Welcome!
    </h2>
    <p className="mx-auto mt-3 max-w-md text-base text-gray-500 sm:text-lg md:mt-5 md:max-w-3xl md:text-xl">
      {data.site?.siteMetadata?.description}
    </p>
  </div>
</div>

After completing the design and page layouts. I needed a simple way to publish content, that did not involve writing HTML. Luckily Gatsby made this super easy with its remark transformer, allowing me to write the content sections of the site using Markdown.

Deployment

My end goal here was to have a workflow that was simple and reduced the effort required to publish content. To achieve this, I chose to lean on GitHub Actions. This was mostly chosen out of curiosity, and the opportunity to turn it into a learning experience. As part of this requirement, the expectation was to rebuild and publish the website anytime new commits had been pushed into the upstream git repository.

With the plug and play approach of GitHub actions, this was surprisingly easy with all the “actions” available. I was able to tie it all together in the following workflow.

checkout project -> setup node -> install deps -> build -> publish

I have included my workflow bellow:

name: Gatsby Build and Publish

on:
  push:
    branches:
      - master

jobs:
  build-publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2
        with:
          lfs: true

      - name: Setup node
        uses: actions/setup-node@v2-beta
        with:
          node-version: '14'

      - name: Cache node modules
        uses: actions/cache@v2
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-

      - run: npm install

      - run: npm run build

      - name: Deploy to GitHub Pages
        uses: crazy-max/ghaction-github-pages@v2
        with:
          build_dir: public
          jekyll: false
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Conclusion

I have generally been impressed with Gatsby and Tailwind so far. They have enabled me to easily create a very optimized website that feels “fast and snappy”. The tooling was able to compress the homepage down to around 1 MB of data including all HTML, CSS, JavaScript, and image files. Then after the initial load, all other pages then get loaded via asynchronous browser requests.

GitHub Actions was another tool that impressed me with its ease of use and easily rivals GitLab CI/CD. I will take what was learned here to work on replacing Travis CI and CircleCI in my other projects.

One additional consideration I did have, was to use Next.js for the website. However, at the time of build. Next.js’ support for static site generation was not on the same level as Gatsby‘s. One of the missing items was image optimization.