Deploy a GatsbyJS blog on GitHub Pages

This article was originally written for my blog. This can explain the way this post is written. The technical point still stand on its own though.

Introduction

Hi there !

What better way to start my blog than by explaning how it works ?

This blog was built using the gatsby-starter-blog starter.

GatsbyJS is a static site generator using the React JavaScript framework. This framework allows us to easily deploy our site to various platforms, such as Netlify or in our case GitHub Pages.

The following Github Pages configuration will allow you to deploy your own blog in a path (username.github.io/reponame).

This setup allows you to deploy your own blog for free, how cool is that ?

Prerequisites

If you want to do the same thing as I did, here is what you need :

• A version of Node JS>=8.11.3
• The Gatsby CLI. Follow the link for instructions on how to install
• A free GitHub account

Local installation

Gatsby provides different starters that will help you start developing your site.

You can even submit your own starters to be featured in the Starter Library !

To create a new local repository containing the Gatsby Starter Blog, use the following command :

gatsby new blog https://github.com/gatsbyjs/gatsby-starter-blog

This command will create and put the project files in the blog folder, as well as run the npm install command.

After that, execute the following commands and start coding !

cd blog
gatsby develop

If you need more information on Gatsby starters, here is a link to the Gatsby documentation on the subject.

This tutorial only covers the deployment of the site.

GitHub Pages setup

To deploy your local Gatsby site to GitHub Pages, you will need to add the gh-pages package to your project.

npm i gh-pages --save-dev

Additionally, you will need to specify the deployment folder in which your site will be in gatsby-config.js.
For our example (username.github.io/reponame), add a path prefix as follows.

module.exports = {
  pathPrefix: "/reponame",
}

Finally, add the following script to your package.json.

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

Now you can run the npm run deploy command to build your site and deploy the content of the public folder to your gh-pages branch.

If this tutorial doesn't suit your GitHub Pages deployment case, more information is available in the Gatsby documentation.

That's it ! Your site should be available to the desired path !