Gatsby Site on Github Pages

Prior to learning about Github Pages, I've always hosted my personal site on my own server instance. This started on a Host Gator shared instance and later on my Digital Ocean droplet.

I eventually realized that the cost of these personal server instances weren't worth it for me anymore. I ran most of my personal scripts from my local PC and all other work related scripts were running from work servers. So it was time to shut them down.

That said, I didn't want to lose the public presence of mine or my wife's personal sites.

Enter Github Pages

As of 2022, there are a number of places you can host a personal site for free. For my needs, I found Github Pages to be the best fit.

Github Pages has a native integration with the static site generator Jekyll, but I wanted to use Gatsby JS due to it being built with Node JS and React.

Finding a Gatsby Theme

For my purposes, I just wanted a simple theme where I could post code related content. I ended up really liking this theme Gatsby-Starter-Tech-Blog. After cloning the theme to my local, I ran the following to get it setup for develop purposes from within the project folder.

npm install
gatsby develop

Note, I recommend setting the gatsby develop script as an npm run command in your package.json as well.

After modifying the React components to my liking, (mainly adding personal links, etc) I then moved on to setting up a repo for my Github Pages site.

Setting up the Github Pages repo

If you have a personal Github account, you're allowed to open a Pages site with the same name as your account. You can also use a custom domain, but for my case I was happy to have my account as username.github.io.

I recommend following along with the Quickstart guide to get setup, but the general idea is as follows:

• Sign into your personal Github account.
• Create a repo in this fashion: username.github.io
• Create a branch called gh-pages
• Within the repo's settings go to the Pages tab
• Set the source branch to gh-pages
• Set the folder to (root)
• Be sure Enforce HTTPS is checked

At this point, your Github Pages repo is ready to go!

Defining a backend in a static site

As a long time Wordpress user, the typical setup I'm fond of is one where the CMS (drafts, hidden content, code) lives separately from the public site.

This separation of concerns makes it easier to track changes between what was done in the Node / React code and what is compiled to the front end as static HTML / CSS / JS.

For my case I like to set up a private repo where the uncompiled Gatsby JS code lives, that will compile on my local PC and push the static public content to my Github Pages repo.

To do so, I open a new private repo and clone it onto my local. I add the initial commit of the Gatsby theme from earlier and push that to the new private repo. Now all changes done to the content and code here are tracked in that private repo.

Structuring your public and private repos

The next step is on the command line from within your local Gatsby private repo's directory.

Do a git clone of your Github pages repo from within your local Gatsby directory like so:

git clone git@github.com:username/username.github.io.git

This will make your local private repos directory look like so:

- node_modules/
- public/
- src/
- username.github.io/
- .gitignore
- gatsby-config.js
- gatsby-node.js
- package-lock.json
- package.json
- README.md

Note, your directory may not be exactly as shown above

Next you'll want to go into your .gitignore file and set the following rule:

username.github.io/

This prevents your private Git repo from tracking the public site as well.

Installing gh-pages node package

Now from within your private repo, change directories to your public repo and install the npm package gh-pages. Here's are the commands:

cd username.github.io
npm i gh-pages

For easy run purposes, define the following in the new package.json file in your public Github pages repo:

"scripts": {
    "deploy-ghp": "gh-pages -d public"
}

Now change directories back to your private repo with a quick

cd ..

Pushing content to your public GH pages

It's finally time to go live!

This part will play out as follows:

• Remove the public/ folders that may exist in the both the local private repo and public repo directory
• Build the public theme with gatsby build
• Copy the new public/ folder to the local public repo
• Run gh-pages from within the local public repo which will send the static site to your gh-pages branch

If you've been following along up to this point, the following npm run script can be set in your package.json (within the private repo) to build and send to your Github Pages site (be sure to replace username with your Github username):

"ghp-build": "rm -rf public/ && rm -rf username.github.io/public/ && gatsby build && cp -r public/ username.github.io && cd username.github.io && npm run deploy-ghp"

If all the steps work, you should see your command line output with something like so:

success onPostBuild - 0.074s
info Done building in 20.410260638 sec


> @ deploy-ghp /home/user/site-private-repo/username.github.io
> gh-pages -d public

Published

Note, errors may occur during the build or gh-pages push, so be sure to run the commands separately to properly debug using the command line output

Conclusion

I hope this setup works for your purposes and helps to get you started with Gatsby and Github Pages.

In some ways, this process mirrors what you may see in a CI/CD setup on something like Circle CI or Github Actions, but since this is for an individual it's nice to remove the unnecessary complexity and run the scripts from your local PC.

-Patrick