Nigel's Blog

How To Build A Basic Gatsby Site

July 25, 2019

As mentioned already, you are never too old to code and never too young to leverage all the benefits of code.

But as someone who has returned to coding mid life, it can be hard to get started. There are lots of reasons for this but a lot of the complexity comes from the tools that coders use to make their daily life easier- which the tools do, but they make getting started harder.

The complexity of the modern-coders-tools can also obscure the basic concepts. This post is to get to bascis for building a website using a modern static website builder called Gatsby.

One basic tool we can't avoid discussing is Yarn. Modern coding can't really be done without Yarn. Basically Yarn is how you can start a coding project which stores all the basic components in a file called package.json.

Enough said, lets get started. This tutorial will teach you how to build a basic gatsby website.

1. Create A Package.json File ("the Recipe File")

Gatsby depends upon a javascript library called React (which was built by Facebook and now powers a good proportion of all the pretty websites and apps you probably use). So to get started with a basic Gatsby site from your Mac terminal:

mkdir my-site
cd my-site
yarn init -y
yarn add gatsby react react-dom gatsby-plugin-mdx @mdx-js/mdx @mdx-js/tag

All we have done so far is create a new directory, with a fresh package.json file and then added the Gatsby and react packages to our package.json file (we also added some gatsby extras like mdx but don't worry about those right now).

Once yarn has finished, you should have a file called package.json in the directory my-site that looks like this:

  "name": "simple-gatsby",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "dependencies": {
    "@mdx-js/mdx": "^1.1.0",
    "@mdx-js/react": "^1.0.27",
    "gatsby": "^2.13.39",
    "gatsby-plugin-mdx": "^1.0.16",
    "react": "^16.8.6",
    "react-dom": "^16.8.6"

This file is like a recipe that will pull in other code ("dependencies") that will be used by use without really knowing we are using that code. You can name your "recipe" whatever you like but it defaults to the folder name. The main variable is where package.json will know where to start our code from (in this case index.js file; or in our case because we are using mdx, a index.mdx file).

2. Add Gatsby File

A basic gatsby website needs one file gatsby-config.js in the same directory as the package.json file:

// gatsby-config.js
module.exports = {
  plugins: [`gatsby-plugin-mdx`]

If you now run yarn gatsby develop and head to http://localhost:8000/ in your browser you will see an empty page.

Which doesn't seem very impressive, but you do have a website now running locally on your computer!

3. Add A Page To The Website

Gatsby has some excellent ways to automatically build web pages from content you give it. But here we are going to use MDX to get a single page up and going. Create a new file at src/pages/index.mdx. This will turn into our home page at /.

Add some content to the file:

// src/pages/index.mdx
# Welcome!

This is the home page

Re run yarn gatsby develop and your new home page should be there.

And that is how to build a basic Gatsby website. The bare bones.

Nigel Gordon

Hi. I'm Nigel Gordon and here are my musings on business, investing, startups and growth. Follow me on Twitter