Build a GatsbyJS website

This post was made after a react meet up talk by me about GatsbyJS. The talk was given in February 2018 and was meant to teach developers about GatsbyJS. This talk was given prior to GatsbyJS gaining its popularity.

The talk is available here - https://www.youtube.com/watch?v=saKvpzAYHOw

In this post we will create a barebone blogging website from scratch using GatsbyJs. The purpose being to learn a few basic concepts of Gatsbyjs.

Blogs will be in markdown format and will reside in github.

Step 1: Install Prerequisites - Nodejs & Gatsby

If you don’t have Node.js installed, go to https://nodejs.org/ and install the recommended version for your operating system.

Install the Gatsby CLI as below:

npm install --global gatsby-cli

Step 2: Install the barebones gatsby starter kit for this blog.

We will do a git clone followed by a npm install of the starter kit. Note[Optional read]: Gatsby provides a gatsby new command which does a git clone followed by an npm install. But we will not use that, as we want to checkout branches from the git repository further down the tutorial.

git clone https://github.com/Jaikant/gatsby-blog-starter
npm install

The starter kit above is the default starter kit with a few extra plugins to process markdowns and images for our blogs.

Step 3: Take a peek at the starter kit.

TLDR: The gatsby develop command starts the dev server, The page directory in gatsby contains the pages.

Now, lets take a look at the gatsby structure.

    src
    ├── pages
    │   ├── index.jsx
    ├── templates
    │   └── ...
    └── layouts
        └── index.jsx

The pages directory is a special one for gatsby. Any .js file created here is detected by Gatsby and is converted into a page.

The src/layouts is another directory which is worth taking a look at now. This directory contains the layout of the page, more specifically the ‘header’ which will be constant across all pages.

The src/templates directory is of importance as well, but we will look into it at a later step.

The src/components directory is a place where we can place our react components. We named it components, but it can be named anything.

Now, lets learn how to run gatsby in our development environment. In the development environment we will run the below command. Gatsby provides hot reloading in the development environment for both code and styles.

cd gatsby-blog-starter/
gatsby develop

On successful start, you will be able to access the development server at http://localhost:8000. On opening this link …

Now, Lets look at the source code for this page.

cd src/pages/
vi index.js

import React from 'react'
import Link from 'gatsby-link'

const IndexPage = () => (
  <div>
    <h1>Hi people</h1>
    <p>Welcome to your new Gatsby site.</p>
    <p>Now go build something great.</p>
    <Link to="/page-2/">Go to page 2</Link>
  </div>
)

export default IndexPage

Thats about it, the index.js contains all the code needed. Now lets take a look at the directory structure:

Step 4: Lets get our sample blogs.

TLDR: Markdown is passed as props to react components

Lets pull some sample blogs from github.

git checkout markdowns

Assuming you are in the ‘src/pages’ directory. If you list the files in the directory. You will be able to see the markdown file(index.md) and an image file within the directory.

.
└── src
    ├── pages
       ├── index.js
       └── dayara-bugyal
       |    ├── index.md
       |    │-- dayara.jpg
       └── gaumukh-tapovan
       └── hampta-pass
       └── kuari-pass

We will use the image for the blog previews as well as for the cover picture for the blog.

Lets take a look inside the index.md. These markdown file will be added to the gatsby data layers and we will pull the content of these files into our react components using graphQL. The content of the markdown will be passed as props to the react components. For now, you could just see the simple structure of the file.

---
title: "Dayara Bugyal Trek"
---

![](dayara.jpg)

Dayara Bugyal is perhaps one of the most beautiful alpine meadow in India. The meadow stretches out far and wide. The panoramic view of the Himalayas from here is breathtaking. Situated at an elevation of about 3048 m, this vast meadow is second to none in natural beauty. The trek goes through open stretches and dense forest at different places. In winters the meadows are covered with snow & look extremely beautiful.
...

Step 5: Lets build a preview of our blog posts

Now lets create a blog preview in the first page. We would have to stop gatsby dev server by pressing a ctrl + C in the terminal in which it is running.

Now in the other terminal, lets checkout the blog-preview branch.

git checkout blog-preview

After checking it out, lets restart the gatsby dev server. (from a different terminal)

gatsby develop

We should now see this at http://localhost:8000

In this branch, we have modified the /src/pages/index.js \. We have included a graphQL query at the bottom of the react component. During the gatsby build/develop/bootstrap process, this query is run and the output is passed as data to the react component.

The graphQL query in the index.js is as follows:

export const BlogsQuery = graphql`
  query blogsQuery {
    allMarkdownRemark {
      edges {
        node {
          id
          frontmatter {
            title
          }
        }
      }
    }
  }
`

Lets look at the output of this query. GraphQL provides an interface to run queries. Lets open this interface on our browser. http://localhost:8000/___graphql

Cut and paste the query below in the left hand column of graphiQL and click the run icon on top.

{
  allMarkdownRemark {
    edges {
      node {
        id
        frontmatter {
          title
        }
      }
    }
  }
}

The output of the query will be something like below. Just observe the node and its fields which come from the markdowns. The edges and node are central to the gatsby data layer. All data in gatsby is modelled around the node. If interested you can read about that here, but it is not really needed for this tutorial. https://www.gatsbyjs.org/docs/node-interface/

{
  "data": {
    "allMarkdownRemark": {
      "edges": [
        {
          "node": {
            "id": "/Users/jai/temp/gatsby-blog-starter/src/pages/gaumukh-tapovan/index.md absPath of file >>> MarkdownRemark",
            "frontmatter": {
              "title": "Gaumukh Tapovan - Source of the ganges"
            }
          }
        },
        ...

Now lets look at the index.js we modified. The graphQL result is contained in data. We simply map through data.allMarkdownRemark.edges and print the title.

const IndexPage = ({ data }) => (
  <div>
    {
     data.allMarkdownRemark.edges.map((post, index) => {
       return (
         <div style={{padding: '16px'}}>
           <Link to={"/"}> <h1> {post.node.frontmatter.title} </h1> </Link>
         </div>
       )
      })
    }
  </div>
)

Step 6: Lets add images to the preview.

Lets add an image to the blog preview.

First lets stop the gatsby dev server.

Lets checkout the blog-preview-images branch.

git checkout blog-preview-images

Now lets restart the dev server in another terminal, but before lets delete the .cache directory as it will contain some stale query results.

rm -r .cache
gatsby develop

Our screen looks like this now. We modified the index.js and the graphQL query. We also changed one other thing, if you find out what that is, do let me know :)

Step 7: Lets create all the blog pages.

Stop the gatsby dev server.

git checkout blog-posts

Restart the gatsby dev server

gatsby develop

And … our pages will look like below, on clicking the blog preview image.

To create the blog pages, we add a template component in src/templates

We then use the Gatsby onCreateNode and createPages API in the gatsby-node.js file.

We essentially run a graphQL query from gatsby-node.js and pass the output of that to the creatPage API to create our pages.

We use the onCreateNode, to add a slug to the markdown fields. The slug determines the url of the page.

Thats about it!

To create a production build, run the following commands and the build will be available in the public directory.

gatsby build

This website can be deployed on netlify in just a few clicks and when intergrated with the code in github, it provides a seamless build and deploy. You would just need to push a blog in markdown format to github and within minutes it would be live, automatically :)

It should be pretty simple to figure it out.

Any questions - feel free to contact me.