Intro

Writing a static site has gotten significantly more difficult than “upload a .html file to a shared host” in the 90s.

This post is talking about how I setup this blog to be hosted on Github Pages and used a Github Action to update on every push to master. It uses Gatsby as the static site generator and I started with a template that lets me use mdx in my posts for interactive React content.

Some of the nice parts of this setup is that I can update the markdown content via the Github online editor (works on mobile and in any browser). Since the Github Action is setup to continuously deploy a new build on every commit to master, I don’t need to clone, build, and redeploy on a local machine.

Setup

On a Mac, get Node.js and Yarn installed. You probably need Xcode tools for git and other tools as well.

Setup global modules for node.js by creating a .npm-global directory as described here.

npm i -g gatsby-cli
mkdir -p ~/Projects/gatsbysites
gatsby new gatsby-gitbook-starter https://github.com/hasura/gatsby-gitbook-starter
cd ./gatsby-gitbook-starter
gatsby develop

I made a bunch of changes to the config.js file and did some work to change the theme of the site from a purple hue to a blue hue.

Then I tested out a static build by doing the following:

yarn build
cd ./public && python -m http.server

Github Pages and Github Actions

Once I knew that a static build would work, I wanted to setup the site so that it could be published to Github Pages.

I created a new public repo on Github, and added my changes:

 git remote add origin <remote repo URL>
 git push -u origin master

Then I wanted to setup Github Pages to automatically publish to the gh-pages branch. I saw that there already existed an action to do that, so I added it to a workflow .yml file in my repo:

<repo>/.github/workflows/main.yml

name: Gatsby Publish

on:
  push:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: enriikke/gatsby-gh-pages-action@2.1.1
        with:
          access-token: ${{ secrets.ACCESS_TOKEN }}
          deploy-branch: gh-pages
          gatsby-args: --prefix-paths

The only thing to note here is that there’s a secrets.ACCESS_TOKEN that is specified in the file.

To create this token, you want to create a personal access token with the repo permissions.

Then in your Repo’s Settings, go to Secrets and create a secret named “ACCESS_TOKEN” with the personal access token you just created.

Now if you make a new change on master and push to the repo, it should automatically publish to the gh-pages branch.

NOTE: Make sure that your Github repository settings have gh-pages as the branch you want to host pages from.

Setting up DNS

Once I had the gh-pages branch setup and autodeploying my changes on commit, I wanted to do one last thing to setup my personal blog - configure my DNS Nameservers to point to Github.

I use Namecheap as my Domain Name Provider, so I followed Github’s instructions on how to properly setup my A records.

I also needed to add a CNAME file in my master branch with the name of my site suyogs.com.

After the DNS changes propagated, I was able to go to https://suyogs.com and it showed my Github Pages site!

Additions

I cleaned up some of the CSS and headers that I didn’t need from the starter template (and changed the color scheme to use a blue hue).

I also removed the need for Jquery and Bootstrap js by making the mobile navigation use React instead. Also made sure that the site mostly worked without Javascript (obvious things like mobile dropdown and live mode JS code don’t work).

Todos

I still need to add commenting and social sharing to the site to allow it to be more interactive and easily shareable. Gatsby has a number of solutions for adding commenting to the site.
React Share is an option for adding social sharing.
Adding an index page with pagination along with an RSS feed would make the site more accessible to read from other sources.

Github Pages for Static Sites