DEV Community

Cover image for Deploy Gatsby website to GitHub Pages
Rahul Jain
Rahul Jain

Posted on • Updated on

Deploy Gatsby website to GitHub Pages

#gatsby #github #react #tutorial

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
Enter fullscreen mode Exit fullscreen mode

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

$ sudo apt update
$ sudo apt -y upgrade
Enter fullscreen mode Exit fullscreen mode

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

$ sudo apt-get install curl
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

Setup Gatsby CLI

$ npm install -g gatsby-cli
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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

├── content
    ├── blog
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

To your package.json, add the following script:

{
    "scripts": {
        ...
        "deploy": "gatsby build --prefix-paths && gh-pages -d public -b master",
    }
}
Enter fullscreen mode Exit fullscreen mode

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`,
}
Enter fullscreen mode Exit fullscreen mode

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`
  ],
}
Enter fullscreen mode Exit fullscreen mode

Deploy the blog 

$ npm run deploy
Enter fullscreen mode Exit fullscreen mode

Get Ready to go live!

Run the following command to make the site live

$ npm run dev
Enter fullscreen mode Exit fullscreen mode

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

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

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

Top comments (5)

Collapse
 
androconsis profile image
Prateek Rathore •

@rahul Jain Great Blog really helped in setting up Gatsby app for Github hosting, I have one question after running the last command the $ npm run dev, do we need to push the master branch to the origin?

Collapse
 
dominicrighthere profile image
dominic-righthere •

because all new github repos will have their default branch name as "main" instead of "master", you'll either have to change your repo's default branch to "master" or change the deploy command to "main"

github.blog/changelog/2020-10-01-t...

Collapse
 
fnaquira profile image
Favio Náquira •

Simple article, perfect tutorial, thank you very much :)

Collapse
 
rahuldkjain profile image
Rahul Jain •

Glad you find it useful

Collapse
 
mitramir55 profile image
mitramir55 •

Hi thanks for this great guide! There's a problem though when I try to get "gastby develop". I get this error:
ERROR #10123 CONFIG

not finished open and validate gatsby-configs - 0.240s

Read next

mettasurendhar profile image

Freshman in College? Here’s How I Started with Web Development

Metta Surendhar -

bohdanai profile image

Methods and Implementations of Single Sign-On (SSO)

Bohdan Lukianets -

gitter4coding profile image

The Fastest Way to Build a React Project in 2025 (with the Latest Tools)

gitter4coding -

prince_beec5ccde00b7c6c73 profile image

3d Image carousel rotation illusion using html css and javascript

Prince -