Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 36 ยท Projects and Practice

Project: Build a Markdown Blog with Gatsby

Plan and build a complete Gatsby blog: folder layout, config, slugs, templates, tags, pagination, images and SEO, with a runnable build-pipeline simulation.

Time to combine what you have learned. In this project you will design a complete blog: Markdown posts with cover images, a paginated index, tag pages, previous and next links, RSS and good SEO. Because Gatsby itself cannot run in this page, the real files are shown read-only, and a plain JavaScript simulation of the build pipeline lets you run the central logic and see results.

The goal

A blog where an author only adds a Markdown file to content/posts/, and the site does the rest: a post page, an entry in the index, tag pages, sitemap and feed entries. No code change per post.

Step 1: folder layout

TEXT
my-blog/
  content/posts/
    hello-gatsby/index.md      <- post with its own folder
    hello-gatsby/cover.jpg
    caching-explained/index.md
  src/
    components/layout.js, seo.js, post-card.js
    pages/index.js, 404.js
    templates/blog-post.js, blog-list.js, tag.js
  gatsby-config.js
  gatsby-node.js

Placing each post in its own folder keeps its images beside it, and relative paths in front matter (cover: ./cover.jpg) just work.

Step 2: configuration

Use the plugins from earlier lessons: the filesystem source for content/posts, gatsby-transformer-remark (or MDX), the sharp trio for images (see Dynamic images), sitemap and feed (see SEO). Put siteUrl into siteMetadata.

Step 3: front matter contract

MD
---
title: "Caching explained"
date: 2025-06-10
tags: [gatsby, performance]
description: "How the .cache folder speeds up builds."
cover: ./cover.jpg
coverAlt: "A stack of boxes"
draft: false
---

Write the schema down with createSchemaCustomization (see front matter lesson) so a missing optional field never breaks a query.

Step 4: gatsby-node.js outline

  1. onCreateNode: add fields.slug from the folder name, giving /blog/caching-explained/.
  2. createPages: query all non-draft posts sorted by date. Create one page per post with id, previousId, nextId in context.
  3. Create list pages: ceil(total / 6) pages with skip and limit.
  4. Create tag pages with group.
  5. Ask reporter.panicOnBuild to fail the build on GraphQL errors, never ignore them.

Step 5: templates

The post template queries by $id, renders the title, date, timeToRead, the cover with GatsbyImage, the HTML body, tag links and the previous/next navigation. Its Head export sets title, description, canonical link, Open Graph image (getSrc(cover)) and JSON-LD. The list template receives $skip and $limit, and shows a PostCard for each node plus pagination links.

Simulating the pipeline

The simulation below implements the data-processing core: parse posts, drop drafts, compute slugs, reading time, previous/next, tag groups and pagination, then print a page manifest similar to what Gatsby records in public/. Run it, then change a post (add a tag, flip draft) to see how output changes.

JS Stand-in: the blog build pipeline

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The draft is excluded everywhere: no page, no tag count, no sitemap entry. That is the behavior you want to see in production.

Step 6: the feed and sitemap data

A good habit is to generate every public list from the same filtered query, so drafts never leak into one place and not another. This second stand-in builds both outputs from the same array.

JS Stand-in: one source for list, sitemap and feed

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Step 7: ship it

Deploy as in Deploying Gatsby sites: build command gatsby build, publish directory public, a Node version pinned in .nvmrc, siteUrl set to the real address. Run Lighthouse on a post and on the index. Check the Head output with "view source".

Ideas for extending it

  • A search box using a client-side index (a small JSON file generated at build time).
  • Reading progress and a table of contents from tableOfContents.
  • Series of posts linked in front matter.
  • An RSS feed per tag.
  • Comments loaded after the page via a third-party script with the Script component.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why keep each post in its own folder?

    A cover.jpg next to index.md can be referenced as ./cover.jpg.
  2. 2. Where should drafts be filtered out?

    One missed query leaks a draft.
  3. 3. What should the build do when a GraphQL query in createPages returns errors?

    A broken query would silently create missing pages otherwise.
  4. 4. How many list pages exist for 5 published posts at 2 per page?

    ceil(5 / 2) is 3.

Summary

  • A good blog needs a front matter contract, slug creation, templates, tag pages, pagination and SEO.
  • Filter drafts once, in a shared query, and reuse the result everywhere.
  • Fail the build on query errors; preview the production build before deploying.
  • The same pipeline works for docs, portfolios and knowledge bases.

Next: Project: a portfolio with a contact function