How to Deploy a GatsbyJS Blog on GitHub Pages as a User Site

This article originally published on jarednielsen.com

GatsbyJS is a great option for a static site generator, even if you're unfamiliar with React. It's very easy to use, super snappy, and has a robust ecosystem. Win win win! To deploy a GatsbyJS blog as a User site on GitHub Pages requires some minor additional configurations. According to the docs, your personal User site on GitHub Pages repository must be deployed from master branch. This creates an issue for us (no pun intended). When we run build our master branch will be cluttered with files (not to mention entirely transformed). The solution is to work locally from a develop branch and use gh-pages to deploy to master on remote.

Install GatsbyJS and Create a New Blog

If you're entirely new to this, run the following commands from the command line:

npm install -g gatsby-cli
gatsby new <your-gh-pages-repo.github.io> https://github.com/gatsbyjs/gatsby-starter-blog
cd <your-gh-pages-repo.github.io>
gatsby develop

Your terminal output should read:

You can now view gatsby-starter-blog in the browser.

  http://localhost:8000/

Initialize Git

If you haven't already, create your repository on GitHub and initialize it locally. Add your remote origin; then add, commit and run:

git branch -m develop

This will move your master branch to a new branch named develop. I name mine develop to mirror the GatsbyJS command for local development, but you can name it whatever you like.

If you run git branch, you will notice you don't have a master branch anymore. This is fine and good. If you navigate back to GitHub, you will find your master branch there. You won't push to master. Instead, you will run:

git push -u origin develop

Install & Configure gh-pages

Install gh-pages:

npm install gh-pages --save-dev

To your package.json, add the following script:

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

Note the -b master flag. When we run gh-pages, we will do so from our develop branch, but we want it to deploy to our master.

To deploy, run:

npm run deploy

Draft Branches

When I'm working on a draft for a blog post, I create a new branch and when I'm ready to publish, I merge it with develop, then add/commit/push and npm run deploy.

Using a Custom Domain Name with GitHub Pages

If you own and want to use your custom domain name with your personal GitHub Pages, the set up is fairly easy, but different depending on your DNS provider. I refer you to the GitHub Help article on Using a custom domain with GitHub Pages for your specific situation.

Add your CNAME file to your static directory in your develop branch. The CNAME file only needs to contain the name of your domain, so, in my case there is one line that reads:

jarednielsen.com

Happy blogging!

I write a weekly newsletter where I share articles about programming, problem solving and lifelong learning. Join now