Publishing Gatsby blog. Part 1.

As promised in my first blog post, I’m sharing how I set up a Gatsby blog and deployed it to Github Pages. There is a lot of material on the Internet on this particular topic, but I still want to document my experience in case I need to do it again.

I split this into two posts. Here is what we’ll cover in this one:

1. How to install Node.js and Gatsby on MacOS.
2. How to create a blog from a blog-starter template.
3. Explain project structure and how it works.

Publishing to GitHub pages will be in the next post.

Installing our tools

To build a website with Gatsby.js, you need to install Node.js. Node is a JavaScript runtime built on Chrome’s javascript engine. Just like you need JRE to run Java apps, you also need some environment (e.g., a web-browser) to run javascript programs. Node.js lets you run javascript without the browser. It also comes with a package manager, which gives you access to thousands of libraries and tools.

Installing Node.js

You may go ahead and install the latest stable Node version. But because there are many versions of Node (just like with Java), and different projects might require different versions of Node, there is this tool called “nvm” or Node Version Manager. Usually, you would install this first and then use it to install a desired version of Node.js. The advantage of using nvm is that you can have several versions of Node.js and switch between them with a command.

To install LTS version of Node.js on MacOS run these two commands:

# installing VVM
brew install nvm
# installing LTS version of Node.js
nvm install --lts

Run node --version to check the installed version.

Installing Gatsby CLI

Gatsby.js is not just a JS framework, it’s a toolkit that, among other things, includes a development HTTP-server, web GraphQL IDE. To manage it all, they ship a command-line tool, aka Gatsby CLI, which can be installed with npm:

# install Gatsby CLI globally
npm install -g gatsby-cli

Creating a blog with Gatsby

You can create a new website with gatsby new and write initial boilerplate yourself, but CLI tools provide a convenient way to create a project from a variety of templates. I chose the simplest thing that is available out there, which is Gatsby Starter Blog.

Creating website from a template

Navigate to the directory where you want to create your project and run the following command (replace YOUR-PROJECT-NAME-HERE with the name of your project):

npx gatsby new YOUR-PROJECT-NAME-HERE https://github.com/gatsbyjs/gatsby-starter-blog

Gatsby will create a directory and set up a website based on provided template.

You can run your website with gatsby develop.

Project structure

Here is how my project structure looks like as of now:

./
├── package.json
├── gatsby-browser.js
├── gatsby-config.js
├── gatsby-node.js
├── src
│   ├── components
│   │   ├── bio.js
│   │   ├── layout.js
│   │   └── seo.js
│   ├── images
│   │   ├── gatsby-icon.png
│   │   └── profile-pic.jpg
│   ├── normalize.css
│   ├── pages
│   │   ├── 404.js
│   │   ├── index.js
│   │   └── using-typescript.tsx
│   ├── style.css
│   └── templates
│       └── blog-post.js
├── content
│   └── blog
│       ├── creating-blog
│       │   └── index.md
│       └── hello-world
│           └── index.md
├── public
│   └──...
└── static
    └── ...

All these files and directories have the following functions:

• package.json – is a file that lists project build config and dependencies.
• gatsby-config.js – main configuration file of gatsby site, contains plugin declaration and setup.
• gatsby-browser.js – allows customization/extension of default Gatsby settings affecting the browser.
• gatsby-node.js – the main module that will be invoked by Gatsby to generate website pages.
• src – the derectory with the website’s javascript code that will be run by Gatsby and gatsby-node.js to render pages.
• src/components – a directory where we can put reusable react components.
• src/pages – the code used to render pages: each js file will generate its own page.
• src/teplates – similar to previous, but will be used for generating multiple pages (like blog posts).
• content - contains directories with Markdown files that will be transformed into blog posts.
• public – output directory with a generated website.

How it works

This is what happens when you run gatsby develop:

1. Gatsby will run the code from gatsby-node.js, and applies plugins and config provided in gatsby-config.js and gatsby-browser.js.
2. Gatsby will generate index and 404 pages using code defined in src/pages directory. They will be rendered with Layout component defined in src/components/layout.js.
3. Pluging will be applied at different steps of the build process.
   • Particularly, plugin gatsby-transformer-remark will scan contents folder and transform all markdown into structured data, that can be retrieved with GraphQL API.
   • gatsby-plugin-feed will generate RSS feed.
4. gatsby-node.js will query for all blog posts and generate pages for them during build time using src/templates/blog-post.js component.
5. Generated content is placed into public folder and served by local HTTP server at http://localhost:8000/.

Customizing your website

The main focus for me was to get rid of old content and figure out how everything works by tweaking some things. All I did is:

• Removed old content and replaced with my own (including site meta data).
• Fixed some CSS, e.g., fixed round avatar on Safari.
• Added two meta parameters to blog posts: “updated” and “draft” and used them in pages.
• Added read time estimate (via plugin gatsby-remark-reading-time).

My initial impression of the code and project in general was pretty poor. I have only been using strongly typed languages, and when I first saw the code in the project, I thought it was a mess. I thought it would take me a lot of time to figure things out and get the blog going. In the end, I quickly picked up the main idea of how it works, and now it is not as scary as it initially seemed.

Conclusion

I’ve set up Node.js on my Mac, installed gatsby, and created a simple blog. In my next post, I will describe how I published the website to GitHub Pages and set up auto-deployment.

Thanks for reading.