Build and Host your Own Blog with Gatsby and GitHub Pages for Free

Introduction

---
title: "A blog article"
some_other_property: some-value
---

...

1. Generate a new Gatsby project in a new git repo connected to a GitHub repo.

2. Configure Gatsby with the plugins we're going to need for parsing the markdown into HTML.

3. Add our first article markdown file.

4. Understand how Gatsby uses GraphQL and write our first query for page content and metadata.

5. Dynamically generate the blog pages from our markdown files.

6. Create a template to display the blog post pages.

7. Deploy our project to GitHub Pages.

Generate a new Gatsby project

npm init gatsby

# (cd blog)
git init
git remote add origin <your-remote-repo-url-goes-here>

Configure Gatsby plugins

# These libraries parse our markdown into HTML (including images and code blocks).
npm i gatsby-transformer-remark gatsby-remark-images gatsby-remark-prismjs prismjs gatsby-remark-highlight-code

# This library allows you to query the data from your markdown files (e.g., the titles of articles).
npm i gatsby-source-filesystem

# These libraries allow us to render image components.
npm i gatsby-plugin-image gatsby-transformer-sharp gatsby-plugin-sharp

# This library will allow us to add a manifest (in particular, a favicon) to our site.
npm i gatsby-plugin-manifest

// gatsby-config.js
module.exports = {
  siteMetadata: { ... },
  plugins: [
    'plugin-name',
    ...
    {
      resolve: 'plugin-name',
      options: {
        plugins: [ /* more plugins here */ ]
      }
    }
  ]
}

// src/components/BlogPreviewCard/BlogPreviewCard.jsx
import { navigate } from 'gatsby'
import { GatsbyImage, getImage } from 'gatsby-plugin-image'

export const BlogPreviewCard = ({
  title,
  slug,
  thumbnail,
  thumbnail_alt,
  author,
  minsToRead,
  datePublished,
}) => {
  const navigateToPost = () => navigate(slug)
  return (
    <StyledCard onClick={navigateToPost}>
      <GatsbyImage image={getImage(thumbnail)} />
      {/* Write some code here that uses the props and returns a card component */}
    </StyledCard>
  )
}

Write your first article

---
title: "Article One"
slug: blog/article-one
thumbnail: "./thumbnail.png"
thumbnail_alt: "thumbnail description"
author: "Your name"
date: 2021-08-01
---

<the-body-of-your-article-goes-here>

Understanding Gatsby and GraphQL

import { graphql } from 'gatsby';

const SomeComponent = ({ data }) => { ... }
export default SomeComponent;

export const query = graphql`
  // Quey goes here
`;

// src/pages/index.js
import { graphql } from 'gatsby';
import { BlogPreviewCard } from '../components/BlogPreviewCard/BlogPreviewCard'

const IndexPage = ({
  data: {
    allMarkdownRemark: { edges }
  }
}) => (
  <SiteLayout>
    ...
    {edges.map(({
        node: {
          frontmatter: { slug, ..., thumbnail },
          timeToRead
        }
      }) => (
      <BlogPreviewCard slug={slug} ... thumbnail={thumbnail} />
    ))}
  </SiteLayout>
)
export default IndexPage

export const query = graphql`
  query {
    allMarkdownRemark {
      edges {
        node {
          timeToRead
          frontmatter {
            slug
            title
            date
            author
            thumbnail_alt
            thumbnail {
              childImageSharp {
                gatsbyImageData(
                  width: 800
                  placeholder: BLURRED
                  formats: [AUTO, WEBP, AVIF]
                )
              }
            }
          }
        }
      }
    }
  }
`

Generating pages from markdown files

// gatsby-node.js
const path = require(`path`)

exports.createPages = async ({ graphql, actions: { createPage } }) => {
  const {
    data: {
      allMarkdownRemark: { edges }
    }
  } = await graphql(`
    {
      allMarkdownRemark(sort: { fields: [frontmatter___date], order: ASC }) {
        edges {
          node {
            frontmatter {
              slug
            }
          }
        }
      }
    }
  `)

  edges.forEach(
    ({
      node: {
        frontmatter: { slug }
      }
    }) => {
      createPage({
        path: slug,
        component: path.resolve(`./src/templates/BlogPost/BlogPost.jsx`),
        context: { slug }
      })
    }
  )
}

Create our blog post template

// src/templates/BlogPost/BlogPost.jsx
import { StaticImage } from 'gatsby-plugin-image'

const BlogPost = ({
    data: {
        markdownRemark: { html }
    }}
) => (
    <SiteLayout>
      ...
      <div dangerouslySetInnerHTML={{ __html: html }} />
    </SiteLayout>
)
export default BlogPost

// You can also grab any extra fields from the frontmatter that you need
export const query = graphql`
  query ($slug: String!) {
    markdownRemark(frontmatter: { slug: { eq: $slug } }) {
      html
      frontmatter {
        ...
      }
    }
  }
`

Deploy to GitHub Pages

npm install gh-pages --save-dev

{
  ...
  "scripts": {
    "deploy": "gatsby clean && gatsby build --prefix-paths && gh-pages -d public -b gh-pages",
    ...
  },
  "dependencies": { ... }
}

Summary

• How to generate a new Gatsby project.

• How to add and configure Gatsby plugins to customise your site.

• How to query Gatsby site data through GraphQL.

• How to dynamically generate pages from a template.

• How to deploy a Gatsby project to GitHub Pages.