Deploy Gatsby website to GitHub Pages

Gatsby is a free and open-source framework based on React that helps developers build blazing fast websites and apps. GatsbyJS is a great option to create a blazing fast modern site. It’s very easy to use, super snappy and has a robust ecosystem.

I've created and deployed my blog using the below steps.
This article will help you to generate gatsby site and deploy it on Github Pages. I'll be using Linux throughout the article.

Step 1. Setup your development environment in Linux

Open the terminal and follow the below steps sequentially.

Install node.js and npm

# install nodejs
$ sudo apt install nodejs

# verify the installation
$ node -v

# install npm
$ sudo apt install npm

# verify the installation
$ npm -v 

Make sure your Linux distribution is ready to go run an update and an upgrade:

$ sudo apt update
$ sudo apt -y upgrade

Install curl which allows you to transfer data and download additional dependencies:

$ sudo apt-get install curl

After it finishes installing, download the latest nvm version:

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.1/install.sh | bash

# verify the installation
$ nvm --version

Install & Setup Git

$ sudo apt install git

# verify installation
$ git --version

# configure git username
$ git config --global user.name "rahuldkjain"

# configure git email
$ git config --global user.email "rahuldkjain@gmail.com"

Setup Gatsby CLI

$ npm install -g gatsby-cli

Create Gatsby Blog

# generate new blog using starter
$ gatsby new blog https://github.com/gatsbyjs/gatsby-starter-blog

# change the working directory
cd blog

# start the development server
$ gatsby develop

View your site locally
Open up a new tab in your browser and navigate to http://localhost:8000/

Congrats, you have successfully setted up the development environment locally.

Step 2. Configuring the blog

This starter blog supports the content in markdown. So let's create a new blog HelloWorld.md

# in HelloWorld.md
---
title: "Hello World"
date: 2020-05-17 16:21:13
description: 'This is my first blog'
---

Lorem Ipsum is simply dummy text of the printing
and typesetting industry. Lorem Ipsum has been the 
industrys standard dummy text ever since the 1500s,
when an unknown printer took a galley
of type and scrambled it to make a type specimen book.

Now copy and paste HelloWorld.md file in content/blog/

├── content
    ├── blog 

Tada! You have created your first blog. Go to http://localhost:8000/ to see your blog.

Now create as much as blog you need in markdown format and put it in the content/blog directory.

Change personal info for the blog
Open gatsby-config.js and edit personal details like title, author-name, siteUrl etc.

Change Profile Picture
To change the profile picture, copy and paste your profile pic in content/assets/ and rename it to profile-pic.png

Step 3. Deploy gatsby blog on Github Pages

Create your repository on GitHub and initialize it locally. Add your remote origin as

$ git remote add  origin https://github.com/<your-github-username>/<repository-name>.git

# very remote
$ git remote -v

# it will look like this
> origin  https://github.com/user/repo.git (fetch)
> origin  https://github.com/user/repo.git (push)

We will work locally from a dev branch and use gh-pages to deploy to master on remote.

$ git checkout -b dev

# verify current branch
$ git branch

# it will look like this
> *dev
> master

Great you are now in dev branch.
Copy the whole project in this repository locally.
Add .gitignore file in the root directory and these commands

node_modules
.cache

It will ignore the files which need not to be in the github repository.

Now push the project files from local to github repository as

$ git add .
$ git commit -m 'commit message'
$ git push -u origin dev

Note that the blog will be served from master branch, so it should only contain the static files which will be generated by building the project in public folder of root directory.

Install and configure gh-pages

$ npm install gh-pages --save-dev

To your package.json, add the following script:

{
    "scripts": {
        ...
        "deploy": "gatsby build --prefix-paths && 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.

Configure gatsby-config.jsto add path prefix
Gatsby blog could be hosted on GitHub Pages at https://rahuldkjain.github.io/blog/.

Each of these sites need a prefix added to all paths on the site. So a link to /hello-world/ should be rewritten as /blog/hello-world.

// in gatsby-config.js
module.exports = {
  pathPrefix: `/blog`,
}

Configure gatsby-config.js to support offline functionality (PWA)
Add the following string in plugins array of gatsby-config.js

// in gatsby-config.js
module.exports = {
  plugins: [
  `gatsby-plugin-offline`
  ],
}

Deploy the blog

$ npm run deploy

Get Ready to go live!

Run the following command to make the site live

$ npm run dev

Tada! You have successfully created and hosted your blog on Github Pages.

I took reference from these tutorials to come up with this article

• https://www.gatsbyjs.org/tutorial/
• https://jarednielsen.com/deploy-gatsbyjs-github-pages-user/

If you find this tutorial helpful, then don't hesitate to hit the love button.
Happy Coding!