Building an interactive personal blog with React and Gatsby JS

I've always wanted a personal blog. A small piece of the internet that I could call home. I also really wanted a blog that I created from scratch. While I could have very easily turned to tools like Squarespace or Medium, the idea of owning my own website that I built from scratch was something that was very appealing to me. I wanted to learn how to build websites, and the tools needed to build them.

Unlike existing blogs, I also wanted to build a blog that could be interactive. I believe that blogs could have an incredible amount of potential as an interactive form of reading. As a simple example, you could press a button in order to change its internal state (something like this button here ). A more complicated example might involve a reader interacting with visualizations, code examples, graphs, or other objects. Many existing blogging tools just didn't have this option (or if they did, I couldn't find it), so I decided to build my own.

It seems fitting then that my first blog article should be about its own creation. In this article, I discuss how I built this interactive personal blog using the React and Gatsby JS frameworks. I'll go from the design process, to its implementation, to how I hosted it on GitHub Pages. I've also open sourced this blog under the MIT License, and it is available at GitHub for anyone to use or learn from.

Requirements

Off the bat, I knew I wanted two things from my blog.

The ability to write interactive content. Visualizations, graphs, and custom calculators for example.
For people to reach my pages via search engines.

I also wanted to use React for my interactive content.

Gatsby helps solve all of the above requirements. It generates static pages that are then "hydrated" with React code on the client side. Having static, pre-rendered pages is important for search engine web-crawlers, since they can't normally read the JS code in the otherwise empty single page app that React would generate.

I, ofcourse, did not start with Gatsby. I decided to make my life difficult by thinking I could create my own solution to my problems. I wanted to use my own custom webpack, babel, and react configurations, despite knowing of Gatsby's existence. I struggled with this for weeks before swallowing my pride. Do not be like me. Do not make your life difficult. Just use Gatsby.

Design

Design is an incredibly important and often overlooked step of creating a website, particularly for beginner web devs or people (like me) who like coding more than looks. If you are creating a blog from scratch, you need to start with design. I use Figma to design my websites. It's a fairly ubiquitous industry tool that has the distinct advantage of being free (as compared to something like Adobe XD).

To begin, I collected references of blogs that would appeal to my target audience. Since my target audience would be people like me, I collected references from the blogs I like. Once I had my reference material, I decided what elements I liked and disliked. I would include the elements I like, and cut what I dislike.

I used Red Blob Games and Medium as my two main sources of references. The former as an example of a personal blog that I really like (that also had interactive content). The latter I used for something with more broad appeal.

My initial design for this blog can be seen here. There are a few differences here and there between the initial design and the final product you're now reading. I opted for a smaller footer bar without a nav menu and slightly less width for the page contents, but the overall wireframe remained intact.

During this process, I ended up asking myself way more questions about text display than I thought I would initially. What size of text is ideal? How should it reactively scale according to the size of the web browser? What's the ideal number of characters per line (apparently, around 65 characters). I used my browser's dev tools on my reference blogs in order to help answer these question. I wouldn't have made any progress had I not had those references. Long story short, use references!

Implementation

I'll cover the technical implemetation of the blog here. I'll only be covering the "interactive blog" bit, and won't be covering like the styling, css, SEO optimization, etc.

I didn't start a Gatsby project the normal way ( i.e. using npm init gatsby). Instead, I started a Gatsby project from scratch, using:

npm i gatsby react

In order for gatsby to actually build websites from my code, I needed a particular folder structure. I ended up with this:

jasonrobwebster.github.io/
  ├── src/
  |   ├── components/
  |   ├── pages/
  |   |   ├── blog/
  |   |   |   ├── index.jsx
  |   |   |   ├── blog-article-1.jsx
  |   |   |   ├── blog-article-2.jsx
  |   |   |   ├── ...
  |   |   ├── contact.jsx
  |   |   ├── index.jsx
  |   |   ├── tools.jsx
  |   ├── shared
  |   |   ├── styles/
  |   |   ├── devices.js
  |   |   ├── theme.js
  ├── .eslintrc
  ├── .git
  ├── .gitignore
  ├── .prettierignore
  ├── .pretterrc.js
  ├── gatsby-browser.js
  ├── gatsby-config.js
  ├── gatsby-ssr.js
  ├── LICENSE
  ├── package-lock.json
  ├── package.json
  └── root-wrapper.js

For those new to Gatsby, the src/pages/ directory is most important. React components written there will be automatically compiled into their own html pages that are then hydrated on the client side. In other words, I'd be able to write React code in a file named src/pages/page-name.jsx and have it rendered at the /page-name/ endpoint.

The key idea to create my interactive blog posts was to write blogs in React under the src/pages/blog/ directory. I'd then use the /blog/ endpoint (generated by the src/pages/blog/index.jsx file) to route users to the posts. This isn't the most ideal solution: I'll have to write my blogs in code (instead of something like Markdown or an in browser editor) and will have to push my changes to GitHub everytime I write a new article. But, importantly, the solution works, and you wouldn't be reading this blog without this solution.

An example of an interactive blog post would be something that uses React's useState hook:

// src/pages/example-blog.jsx

import React, { useState } from "react"

import { ArticleWrapper } from "../../components"

const exampleBlog = () => {
  const [value, setValue] = useState(0)

  const increaseValue = () => {
    setValue(value + 1)
  }

  return (
    <ArticleWrapper lastUpdated={new Date(2021, 8, 7)}>
      <button onClick={increaseValue}>{`Value: ${value}`}</button>
    </ArticleWrapper>
  )
}

export default exampleBlog

That's it for how I wrote the interactive blog posts. To actually connect the blog posts to my blog root endpoint, I set up a "datastore" to hold the location and metadata for each of my blogs. The slug stored the endpoint, which as discussed above was basically the name of the file that contained my page. I also included a published tag that would hide it from the root page, in case I ever wanted to do that. The "blog datastore" ended up just being a variable that looked like:

// src/pages/blog/index.jsx

// blog card datastore
const blogs = [
  {
    title: "Example blog title",
    description: "Example blog description",
    tag: "Tech",
    slug: "example-blog", // for src/pages/blog/example-blog.jsx
    image: "images/blog.png",
    published: false,
    lastUpdated: new Date(2021, 8, 3),
  },
]

I'd then be able to use this to generate each link to my blog, using a custom built <BlogCard /> component (inspired directly by my Red Blob Games reference, and my love of cards in general):

// src/pages/blog/index.jsx

import React from "react"

import fp from "lodash/fp"

import { BlogCard, PageWrapper } from "../../components"

const Blog = () => {
  const publishedBlogs = fp.filter((blog) =>
    isProduction ? blog.published : true
  )(blogs)
  const lastBlog = fp.maxBy((blog) => blog.lastUpdated)(blogs)

  return (
    <React.Fragment>
      <PageWrapper lastUpdated={lastBlog.lastUpdated}>
        <CardContent>
          {fp.flow(
            fp.sortBy((blog) => -(blog.lastUpdated || new Date())),
            fp.map((blog) => (
              <BlogCard
                key={blog.slug}
                url={blog.slug}
                title={blog.title}
                imageLink={blog.image}
                description={blog.description}
                tag={blog.tag}
              />
            ))
          )(publishedBlogs)}
        </CardContent>
      </PageWrapper>
    </React.Fragment>
  )
}

export default Blog

// src/components/BlogCard.jsx

import React from "react"

import { Link } from "gatsby"

import { HyphenatedText } from "./text"

const BlogCard = ({ url, title, imageLink, description, tag }) => {
  return (
    <React.Fragment>
      <Card to={url}>
        <Card.Content>
          <Card.Image src={imageLink} />
          <Card.Text>
            <Card.Title>
              <HyphenatedText>{title}</HyphenatedText>
            </Card.Title>
            <Card.Description>
              <HyphenatedText>{description}</HyphenatedText>
            </Card.Description>
            <Card.Tag>{tag}</Card.Tag>
          </Card.Text>
        </Card.Content>
      </Card>
    </React.Fragment>
  )
}

export default BlogCard

When all combined (with a little css styling), I'd have a nice set of cards at the /blog/ endpoint, each linking to my published interactive blog posts:

Building an interactive blog with React and Gatsby JS

How I built a personal blog with React and Gatsby JS.

Tech

And... that's about it for the "interactive blog" part of the implementation. The rest of the implementation was basically getting the styles and UI/UX to match my initial design, which I won't cover here.

Deploying to GitHub Pages

GitHub pages is a free way to host a personal blog. In order to set this up, you need to have a repo named <username>.github.io. In my case, that's jasonrobwebster.github.io. Then, in the repo's Settings > Pages, you need to specify the branch that the your site will be built from. Set it to the gh-pages branch. If you don't have this branch yet, create it.

We'll deploy our site using the gh-pages package. This will send a local directory to our repo's gh-pages branch. Since we've set up our repo with the gh-pages branch, this should work off the bat, but we'll require a small configuration line to make sure we upload the public/ directory.

First, we'll install the gh-pages package

npm i gh-pages

Before we deploy our blog, we need to build our pages from our source code. In our package.json, set up the following scripts. Note that we are uploading the public/ directory to the gh-pages branch using the gh-pages -d public script.

// package.json
"scripts": {
  "dev": "gatsby develop",
  "build": "gatsby build",
  "predeploy": "npm run build",
  "deploy": "gh-pages -d public",
  "serve": "gatsby serve",
  "clean": "gatsby clean"
}

Then run

npm run build

Our blog will be built in the public/ directory. To deploy our built website, we run

npm run deploy

Going to <username>.github.io, you should see your built website, ready for anyone to use. And because we're using Gatsby, we have prerendered html pages for search engines to crawl (we're still not optimised for SEO though, to do that we can follow this guide).

Conclusion

We've managed to design, implement, and deploy an interactive personal blog using the React and Gatsby framework. We can use it to write interactive blog posts in React code, and generate an SEO optimized page that we host on GitHub. For any more details, feel free to browse this blog's source code on GitHub.

Build­ing an in­ter­ac­tive per­son­al blog with Re­act and Gats­by JS

Re­quire­ments

De­sign

Im­ple­men­ta­tion