Creating My Personal Website With Gatsby and GitHub Pages

Here’s the repo for the website: https://github.com/2018kguo/2018kguo.github.io

Background

Yesterday, I finally got around to overhauling my personal website (check it out!), and I decided to write up a thorough walkthrough of what I did to get it up and running in order to hopefully save someone else from the googling and troubleshooting that I went through.

The main motivation for rewriting my old website was because it was it was written in purely HTML/CSS with no front-end framework attached, which made it really hard to edit or add new content to the site. I liked the way the old website looked, but its age was showing. Overall I’m really happy with how the new version turned out, especially since I’ve been putting off making it for so long.

The old version of my website

Since I’m familiar with React, I decided to use Gatsby, a React-based static site generator that supports server-side rendering and comes with boilerplate themes to speed up the creation process.

I decided to stick with using GitHub Pages for deployment since it’s free and works fine for my needs, but Netlify is another free option that warrants checking out. The nice thing about GitHub Pages is being able to have your code, configuration variables, and continuous delivery workflows all in the same place.

Initial Setup

For getting started with Gatsby, make sure to follow the steps in the first half of this tutorial, that is, install Node.js and Git if you haven’t already, and then install the Gatsby CLI:

npm install -g gatsby-cli

Navigate to the directory that you want to create your Gatsby-related files in and run:

gatsby new my-gatsby-website https://github.com/LekoArts/gatsby-starter-portfolio-cara

This will set up a new Gatsby site using the cara theme (which I’m using). If you want to pick another theme to build off of, you can browse them here.

For GitHub Pages, all you’ll need to do is create a new repository titled [YOUR_USERNAME].github.io. It needs to be a public repository as well.

The previous command initializes a git repo for you, so first thing to do is to hook it up to our GitHub Pages repository and create and checkout to the dev branch. This is where our Gatsby code will reside. We’ll also create a master branch, where our built files will be deployed.

cd my-gatsby-website 
git remote add origin https://github.com/[user]/[user].github.io.git
git checkout -b dev
git branch master

Go to your repository settings tab on the right and set the source branch to master.

There shouldn’t be anything in your master branch yet, so GitHub Pages URL should display a 404. We’ll set things up so that pushes to the dev branch will trigger automatic updates to the master branch and website.

Editing the Website

It’s time to customize the website. Typically, Gatsby themes define all website content within markdown (.md) files that are more ore less plaintext and quite simple to edit. The theme I chose uses MDX (.mdx), which also allows you to have JSX components within them. For an example, check out this file from my repository and its raw markdown.

Aside from that, you’re more or less dealing with a regular React codebase when it comes to editing site layout, adding new components, etc. For the theme I chose, in order to edit the files that come with the theme, you have to shadow them, that is, you need to mirror the directory paths from src/ and create your own edited version of those files. If you compare my src/ directory with the theme’s, as well as the files within them (notice how the import statements have to be changed), it should be more clear how this is done.

You can preview your changes live while developing with

gatsby develop

And then opening localhost:8000 in your browser. From my experience, for some changes such as adding new files, you may have to terminate and rerun this command to them take place.

Publishing Manually

Now that our website is looking good to go, let’s deploy it!

We’ll be using the gh-pages package to push this to our master branch:

npm install gh-pages --save-dev

Let’s first set up a way to deploy this manually so we can confirm that everything is working properly. Add this script to packages.json (note the -d and -b flags specifying the build directory and output GitHub branch respectively)

{
    "scripts": {
        ...
        "deploy": "gatsby build --prefix-paths && gh-pages -d public -b master",
    }
}

And then deploy the site to the master branch

npm run deploy 

If you check out your master branch now, it should have been pushed to and your GitHub Pages URL should be displaying your site (it may take a minute or so to register the changes, try hard reloading the page as well to discard cached data).

Adding Continuous Deployment

Workflow runs

Now let’s add continuous deployment with GitHub Actions. This will make it so that updates to the dev branch are always propagated to your actual website, so you’ll know they’re always in sync, and save you the extra step of manual deployment. It also will allow you to make changes to the site on a device without Node.js or Gatsby installed, since GitHub will handle the build and deployment rather than our own machine.

On your repo, make sure you’re in the dev branch and then navigate to the Actions tab > New workflow > Set up a workflow yourself. You should see a text editor for your workflow YAML file. This is what I currently have in mine:

• On lines 8–11, you can see that this workflow script only triggers upon pushes to the dev branch
• On lines 26–30, I’m using this action to create a .env file with a variable from a repository secret so that Node.js can read it in as an environment variable. This is needed to set up Google Analytics for your site, which is covered in the next section. For now, even if referenced repository secret doesn’t exist, I don’t believe that having this here does any harm (delete these lines if they cause issues).
• On lines 32–34, we need to temporarily create a public/ directory in case it doesn’t exist because that’s where our Gatsby build files get outputted to. If you don’t have a public/ directory within your dev branch (it’s probably included in .gitignore), then this step is necessary
• Lines 40–49 essentially do the same thing as the deploy script from earlier, "gatsby build --prefix-paths && gh-pages -d public -b master"

Once you commit this workflow file to the dev branch, when you go back to the Actions tab, you should see the workflow spinning up and running its tasks. You can click on it to open a more detailed view and look at output logs as it runs. Viola, upon successful completion, your master branch should be automatically updated, and this will hold true for all subsequent pushes to dev.

Adding Google Analytics (Page Views & Traffic)

Wouldn’t it be nice to see if your website is getting hits? We can accomplish this by linking up our site with Google Analytics.

First, I would follow this guide to get a universal analytics tracking ID for your site. Be sure to enter your GitHub Pages URL in the “Website URL” field while creating the universal analytics property, and make sure that the resulting tracking ID starts with “UA”.

Go to your repository Settings tab > Secrets > New Repository Secret, and create one with the key GOOGLE_ANALYTICS_ID and paste the tracking ID as the value.

Install this plugin for Google Analytics with

npm install — save gatsby-plugin-gtag

In our Gatsby files, within gatsby-config.js , add

require(`dotenv`).config({
   path: `.env`,
})

at the top of the file and

as your first plugin. Your analytics ID will be stored inside a .env file at the root directory of the project like this

GOOGLE_ANALYTICS_ID=”UA-XXXXXXXXX–X"

and read from there at build time. Recall that this .env file is created and populated with the tracking ID during our workflow, which reads it in from your repository secret.

You could also hardcode your tracking ID into the file, but that would just expose it on GitHub. It’s not really the end of the world since I think the worst thing that can happen is someone using your analytics ID and generating a bunch of fake traffic, but it’s obviously a better practice to have it as a configuration variable.

Once you commit this and get this code into master, you should be able to see your analytics dashboard working (You’ll need to turn off adblockers such as uBlock Origin while on your GitHub Pages site, since it will otherwise block traffic between you and Google Analytics).

And that’s all I got. I hope this article was helpful!