Deploy Gatsby website to GitHub Pages
Tags: gatsby, github, react, tutorial
Published: 2020-05-19 12:00:23

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](https://rahuldkjain.github.io/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**
```bash
# 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:
```bash
$ sudo apt update
$ sudo apt -y upgrade
```

Install curl which allows you to transfer data and download additional dependencies:
```bash
$ sudo apt-get install curl
```
After it finishes installing, download the latest nvm version:
```bash
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.1/install.sh | bash

# verify the installation
$ nvm --version
```

**Install & Setup Git**
```bash
$ 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**
```bash
$ npm install -g gatsby-cli
```

**Create Gatsby Blog**
```bash
# 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`
```bash
# 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
```bash
$ 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](https://www.npmjs.com/package/gh-pages) to deploy to `master` on remote.
```bash
$ 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
```bash
$ 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`**
```bash
$ npm install gh-pages --save-dev
```
To your `package.json`, add the following script:

```js
{
    "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.js`to 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`.

```js
// 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`
```js
// in gatsby-config.js
module.exports = {
  plugins: [
  `gatsby-plugin-offline`
  ],
}
```

### Deploy the blog
```bash
$ npm run deploy
```

### Get Ready to go live!

Run the following command to make the site live
```bash
$ 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!