(OLD) About this site: a deep dive

hey! this is for the old version of my site, based on Gatsby. the information herein is not current.

When I set out to build a personal site, there were a couple guiding principles that I wanted to keep in mind.

I wanted it to be fast

This site is pretty minimalist. Stock monospace font, no animations, no crazy colors. I didn't design it like this out of necessity; I would have designed it this way even if I wasn't going for speed. It's readable, and it looks sleek. If every page load was taking two whole seconds or worse, it'd beg the question "what's this site even loading? It's just text on a white background!"

I wanted it to be easy to work with

In the past, I've used the traditional $5 shared hosting that comes with a cPanel interface. I've run builds and manually uploaded the files to the server. The result was a site that I never, ever updated, because the process was just so tedious.

It took a bit of work, a bit of learning, and a lot of time. The end result, though, ticks both of those boxes for me.

The tech

This site is:

built with the Gatsby framework.
hosted using Netlify
deployed from Github, so it builds on a push to master

No, I'm not forgetting anything. That's all.

What is Gatsby?

Gatsby is a JavaScript framework made to be fast, both in terms of performance and development speed. It's based on React, with a whole lot of additions. It implements all those optimization tricks under the hood - lazy loading, resource prefetching, code splitting, and much more.

For the developer, it uses GraphQL to provide a unified API for whatever data you throw at it. Routing "just works"; put a React component into a specified directory, and Gatsby will generate a route to it. It's got a rich, well documented plugin ecosystem with that makes implementing complex features simple and straightforward.

GraphQL

I mentioned that Gatsby builds in a GraphQL API. It provides access to any and all of the data your site uses, whether they're local or external. Need to interface with Shopify? Add a plugin, make some config changes, get your API key (or the Shopify equivalent), and just like that, your built in API has access to your Shopify store.

This site doesn't use Shopify, but it does use Markdown. This blog post is in Markdown, along with every other blog post I've got. Just like with Shopify, Gatsby's markdown plugin provides access to Markdown files directly through the GraphQL API.

Markdown and me

So, what does that do for me? Well, there's a bit more to the plugin than just accessing the files. Let's take a look at some Markdown files and some GraphQL queries.

These are the first six lines of the Markdown file containing my recent post about my quest to develop a comprehensive baseball statistics site.

---
slug: "/blog/baseball-site-intro"
date: "2021-08-16"
title: "Creating a baseball statistics site"
type: "blog"
---

That's a YAML front matter. It's used elsewhere, notably in Jekyll, a static site generator that takes in Markdown and spits out webpages. Gatsby does the same, using the remark markdown processor to generate HTML. The properties specified in the front matter are parsed as well, and it can contains just about any data you like. Now, for the GraphQL.

This query gets all Markdown files, ordered by date, descending.

query blogPostsQuery {
  allMarkdownRemark(
    sort: { 
      fields: frontmatter___date, 
      order: DESC
    }
  ) {
    edges {
      node {
        id
        frontmatter {
          slug
          date
          title
          type
        }
      }
    }
  }
}

Those are the same variables specified in the Markdown file. Gatsby parsed the Markdown file, took the YAML, and put it into the database for us to access anywhere in our application. The query above is used on the home page to populate the list of blog posts.

The formatted HTML is accessed similarly. Here's the query I use to get a specific blog post:

  query blogPostBySlug($slug: String!) {
    markdownRemark(frontmatter: { slug: { eq: $slug } }) {
      html
      frontmatter {
        date(formatString: "MMMM DD, YYYY")
        slug
        title
      }
    }
  }

This query comes from file called blogTemplate.js, which contains a React component where I map the title into an h1, the date into an h4, and the generated HTML into a div.

In the same directory as blogTemplate.js is another file, pageTemplate.js. The about page, like my blog posts, is written in Markdown. At the moment, it's the only non-blog Markdown file. Being able to write pages in Markdown doesn't provide quite the same benefit that writing blog posts does, but I thought I might as well.

The YAML front matter for about.md is as follows:

---
slug: "/about"
date: "2021-05-04"
title: "about me"
type: "page"
---

In order to use the correct template for pages and blog posts, I had to introduce the a new property into the database, type. In order to do this, the process was as follows:

Put the type property into the front matter block of every Markdown file
There is no step 2.

Seriously, that was it. After that, mapping Markdown files to their respective templates was trivial.

Deployment and Hosting

Remember when I mentioned Github and Netlify?

The code for this site is in a private Github repo (though a empty version can be found on my Github at some point). That Github repo is hooked up to Netlify, a hosting provider with a generous free tier and great Git integration. A push to the main branch triggers a build, which typically finishes within 30 seconds.

This leads me to one of my favorite things about this project.

A final point about the blog

I write my blog posts in my editor. I can leave inline comments, view edit history, but above all, I didn't have to set up a CMS for something as simple as a blog.

I could set up a CMS I had to, though, becasue there's a gatsby plugin for that.

---

$ git add . 
$ git commit -m "blog post: deep dive about site" 
$ git push

cityinspain.dev