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

November 26, 2018

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. Plus: there’s the added of bonus of working with React! 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

Customize Your GatsbyJS Blog

Kyle Mathews is a swell guy, but it’s not his blog anymore. You will want to customize it…

In assets, add your own profile picture. You can replace the current .jpg with your own and use the same name, or, if you choose a different file name (or format), you will need to edit the GraphQL query in src/components/bio.js.
While you’re in bio.js, you’ll want to add your own bio and social links.
There are a few things to update in gatsby-config.js:
- siteMetadata: This should be self-explanatory.
- gatsby-plugin-google-analytics: If you’re using Google Analytics, add your tracking ID here.
- gatsby-plugin-manifest: Update the icon property, unless you’re okay using the Gatsby icon.
Lastly, don’t forget the favicon.ico in static!

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!