How to Make a Blog From Scratch Using Gatsby

Bootstrap a fully customizable and slim blog with React

Ferenc Almasi
Jul 21, 2020 · 11 min read
How to Make a Blog From Scratch Using Gatsby
How to Make a Blog From Scratch Using Gatsby
Originally published on webtips.dev
Originally published on webtips.dev

With the recent growth of JAMStack, Static Site Generators — or SSG for short — are becoming more popular again. They provide a great way to simplify the architecture of your blog and make your site faster, more secure, and more responsive. All this without any restrictions. Since you have access to every bit of code that makes up your blog, you can customize it as much as you like.

So what exactly are Static Site Generators?

Static Site Generators are used for generating sites that are only made up of static assets. It’s a middle ground somewhere between using a full-fledged content management system and hard coding every bit of your site.

There’s no backend architecture, no server-side code, and usually no database involved. You create your content by writing Markdown, host it, and you’re all done.

Of course, this often means you don’t have a CMS in place like WordPress that you can use for writing content. So why would you still choose to go with a Static Site Generator?

Why Should You Use a Static Site Generator?

Then comes the question: What are the potential benefits of using a Static Site Generator? Is it really worth it? There are three main benefits of using an SGG instead of a CMS.

The most prominent is the increase in speed. Since your site consists of only static assets, there’s no delay in network requests. No API or database calls are made which results in faster responses. You request a page and the server responds with a single HTML file.

The size of your files is also reduced. When using a CMS, you most likely end up with a bunch of unnecessary code injected into your page. If you don’t have full control over it, it can impact your performance, the accessibility of your site, or even your SEO.

Another great benefit of using a Static Site Generator over a Content Management System is the added security. Since you don’t have any backend or database, there’s nothing really to hack. No sensitive information, all your content is stored in files. This means you don’t have to worry about hackers targeting you.

Last but not least, as your files are static, your development workflow will also be much simpler. You can easily run your site locally as you don’t have to mock data. You can switch hosting without having to worry about backend re-configuration. Since you don’t need to host a database, this also means you can choose a free service such as GitHub Pages and host your blog completely free. As you can see SSGs also have reduced costs.

If you, however, want to go with a paid service to register your own custom domain I recommend going with Bluehost, because they:

  • Provide a Free SSL certificate with your registration
  • Integrate easily with WordPress if you want to use Gatsby with a headless CMS
  • Have a 24/7 support to help you out with problems
  • Provide a 30-day money-back guarantee

Why You Shouldn’t Use a Static Site Generator

While Static Site Generators have many great benefits, as with everything, they also have downsides and is not for everyone. It may not be suitable for you if one of the points mentioned here bothers you.

Since you don’t have a backend interface in place with a database, there’s no option for you to use complex features such as user login, various forms, or more complicated searching and filtering.

As you mostly serve static assets, there may not be a need for CMS. Instead, you publish your content through markdown files. If you have a large team with people who have no experience in coding, it might scare many that you have to work with Git and Markdown. If you still decide you need a CMS, your initial dev time will be increased and you lose the speed advantage of having no API calls.

Having no database and user functionality also means you don’t have the option to have user-generated content on your site. If you need to have forums on your site that can be managed by your visitors, posts that can be written by your community, or anything user-related — which involves registration on your site — then a Static Site Generator might not be an ideal choice.

Since we are talking about static sites, you can’t have dynamically changing data such as “Trending stories” or “Best selling” sections. Unless you integrate your statically generated site with a third party API and heavily use JavaScript on the frontend. But Static Site Generators are not meant for e-commerce platforms or social networks anyway.

Static sites are also hard to scale. Every time you add a new post, the whole site has to be built, increasing build time with each new file. If you only publish content every couple of days and you have no more than a couple of blog posts, then this is not a problem for you. But if you constantly push out new content and you have articles in the thousands, then you will need a CMS.

With that being said, let’s see how they actually work.

How Does Gatsby Work?

There are countless of Static Site Generators out there. You can have a view at StaticGen.com to get a good overview of the available generators out there. In this tutorial, I’ll be focusing my attention on Gatsby, coming in second on GitHub as one of the most popular Static Site Generators.

Static Site Generators listed on StaticGen
Static Site Generators listed on StaticGen

So how does it work? Gatsby uses modern web technologies — such as GraphQL and React — to build your website out of a number of data sources such as content coming from a headless CMS, Markdown files, or a third party API in the format of JSON or other forms of structured data. So even though — as mentioned in the beginning — most of the time you can go without any database or CMS in place, Gatsby still provides an option to make your site more dynamic.

The process of Gatsby
The process of Gatsby

Setting Up Gatsby

No more talking, let’s jump into coding. First, you want to create a new empty directory for your project. To bootstrap Gatsby, you can use the Gatsby CLI to create a new Gatsby project. Run the following command in your terminal:

npm i -g gatsby-cli 

to install Gatsby globally. Then create a new Gatsby project by saying:

gatsby new ssg

This will create a new folder called ssg that will be populated with an initial Gatsby project. Once installed, start the server with npm run start and you should see your Gatsby astronaut live on localhost:8000.

Gatsby astronaut waving back at you
Gatsby astronaut waving back at you

The Structure of a Gatsby Project

Opening up your project structure, you will be greeted with the following structure:

Image for post
Image for post

Let’s go through them real quick to see what each of them are doing.

  • .cache: Used for internal caching automatically created by Gatsby
  • public: Also auto-generated by Gatsby. This folder contains the build output. This is the folder you want to deploy to your live site in your CI.
  • src: This is where you will spend most of your time. This directory contains all of the code of your frontend. Your components, pages or other assets such as images.

If you would like to add other static assets to your site that should not be processed by Gatsby, you can create a static folder at your project root. This will tell Gatsby to only copy them to your public folder.

You’ll also find a couple of configuration files at the root folder:

  • gatsby-browser.js: Used for Gatsby Browser APIs to run code on various browser events, such as onRouteUpdate or onServiceWorkerInstalled
  • gatsby-config.js: Used for configuring your Gatsby site. This is where you can specify metadata for your app, such as your title or meta description. You can also define here the list of plugins you’d like to use.
  • gatsby-node.js: If you are using Node for Gatsby, this is where you can define the related Gatsby Node APIs.
  • gatsby-ssr.js: Lastly, if you use server-side rendering, this is where you would hook into any of the SSR related APIs.

Setting Up Gatsby Plugins

To see how plugins — a core feature of Gatsby —work, let's add SCSS support to the project. Run the following command to install the SCSS plugin:

npm i --save node-sass gatsby-plugin-sass

Inside your gatsby-config.js file, add gatsby-plugin-sass to the end of your plugins array and simply change layout.css to layout.scss inside your components folder. And you’re all done, you can now use SCSS in your project.

If you happen to run into an error saying:

Error: Cannot find module ‘react’

Try removing your node_modules folder and reinstall it with yarn: yarn install.

Adding New Posts With Markdown

Let’s create some posts with markdown to make the site contentful. First, you’re going to need to install a new plugin which is used for transforming markup files to HTML. Run npm i gatsby-transformer-remark and add it to your plugins array. You’ll also need to make use of gatsby-source-filesystem to pull in the markdown files.

This assumes that your markdown files are places inside src/markdown, therefore, create a new folder called markdown inside your src folder, and also add a new post.md.

What you see at the top is a set of metadata called frontmatter. This is denoted with triple slashes and key-value pairs. It will be parsed by gatsby-transformer-remark. Later on, we will be able to pick up this information through GraphQL and use it inside React. The rest of the file will be parsed as an HTML.

If you need some guidance on the basic syntax of Markdown, you can find plenty of examples on Markdownguide.org.

If you head over to your GraphiQL interface at localhost:8000/___graphql, you’ll notice you have a new node inside the Explorer called markdownRemark. This node contains all the information about the markdown files that are relevant to us.

Create the following query to request a post. Don’t forget to set the slug under “Query Variables”.

Requesting the Markdown post from GraphQL
Requesting the Markdown post from GraphQL

As you can see, the query returns a formatted version of the markdown file. You can request it using its slug. The HTML portion of the file has also been parsed. All we have to do now is inject this data into a component and create the pages based on the slug.

To use this data, we’re going to need a template that will show it for us. Create a new folder called templates inside your src folder and add a new file called post.js. You can also copy the GraphQL query as it is needed inside the template. This component will display the data returned by the query.

As you can see, the component will get a data prop that will get the value returned from the GraphQL query which is exported on line:16. So far, we can’t access this component inside the browser as it’s not inside the pages folder. We need to use Gatsby’s Node API to create a new page for every markdown file we have.

For this task, we can use the createPages API. Head over to your gatsby-node.js file and hook into the API by exporting it.

First, export the createPage function from actions. This will be used for creating the individual pages. Next, you’ll also need the component which can be used for creating the pages, and lastly, we want to query the markdown files. This GraphQL query will limit the number of results to 1000 and sort it based on the publish date of the post.

From line:21, we can then loop through the result and create a page for each markdown file. Here you can pass the slug to be used as a path and the component that should be used for the template. If you need to pass extra data, you can also specify a context property.

Gatsby warns you about the need to restart the webserver
Gatsby warns you about the need to restart the webserver

Unfortunately, Gatsby won’t be able to pick up the changes right away, so you’ll need to restart your webserver for the effect to take place. If you go to localhost:8000/intro-to-gatsby, you will now able to see the markdown page you’ve just created.

Now you can create as many posts with markdown files as you’d like.

Displaying the Posts on the Homepage

All that’s left to do is to display the list of posts on the front page of your site. You can easily do this by changing the index.js file inside your pages folder.

First, you want to create a query that helps you collect all available markdown posts. The Explorer tab in GraphiQL provides a great way to create queries with a couple of clicks.

The Explorer tab in GraphiQL
The Explorer tab in GraphiQL
The Explorer tab in GraphiQL

I have created the following query which gets all the posts in a descending order based on their publish date. We’re going to also make use of the id and an excerpt which is automatically created from the first 250 characters of the post.

Just as for the post template, you need to export this query to be able to use it inside the component, which we are going to create now. Above the exported query, change the layout of your IndexPage to the following:

We are only interested in the edges node so we destruct it right away. We can loop through them with map and create a new list item for each post.

With the help of some CSS, you should be able to see your posts on your front page.

list of posts generated by Gatsby
list of posts generated by Gatsby

Summary

Now that you have your blog ready, all you need to do is deploy it. You can use free services such as Netlify, GitHub Pages, or Vercel or go the traditional way and use a paid service such as Bluehost with a custom domain.

Overall, Gatsby provides a great way to create your blog with modern web technologies and make it fast and lightweight. It has more than 2000 plugins for you ready to be used, so chances are, you’ll find one for your problem.

If you still thinking about whether to use Gatsby for your project because of the way content is created — as mentioned in the beginning — you can use Gatsby with a headless CMS. It integrates nicely with WordPress, Prismic, and a couple of other CMS.

Go ahead and give it a try. Have you used Gatsby before? What are your insights? Let us know in the comments! Thank you for taking the time to read this article, happy blogging!

Learn more about JAMStack on webtips.dev
Learn more about JAMStack on webtips.dev

Weekly Webtips

Explore the world of web technologies through a series of tutorials

By Weekly Webtips

Get the latest news on the world of web technologies with a series of tutorial Take a look

By signing up, you will create a Medium account if you don’t already have one. Review our Privacy Policy for more information about our privacy practices.

Check your inbox
Medium sent you an email at to complete your subscription.

Ferenc Almasi

Written by

💻 Frontend dev with a passion for beautiful code • 🐦 Tweets webtips on twitter • ✍️ Writes on webtips.dev • Get in touch @ hello@allma.si or visit allma.si 👋

Weekly Webtips

Explore the world of web technologies through a series of tutorials

Ferenc Almasi

Written by

💻 Frontend dev with a passion for beautiful code • 🐦 Tweets webtips on twitter • ✍️ Writes on webtips.dev • Get in touch @ hello@allma.si or visit allma.si 👋

Weekly Webtips

Explore the world of web technologies through a series of tutorials

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store