Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 36 ยท Markdown and MDX Sites

Front Matter, Tag Pages and Pagination

Group posts by tag, build one page per tag, split long lists into numbered pages with skip and limit, and add previous and next links in Gatsby.

A blog with ten posts needs nothing more than an index. A blog with five hundred needs structure: tag pages, category pages, and a post list split into pages. Gatsby builds all of these from the same data you already have, using createPages. In this lesson you will design front matter, group by tag with GraphQL, and paginate.

Designing front matter

Good front matter is consistent, because every template depends on it. Keep fields small and typed the same way in every file.

MD
---
title: "Understanding Gatsby caching"
date: 2025-05-02
updated: 2025-06-10
tags: [gatsby, performance]
draft: false
summary: "How the .cache folder speeds up builds."
---

Gatsby infers the GraphQL schema from the data it finds. If updated is missing in every file, the field does not exist and a query for it fails. If one file has tags: gatsby (a string) and another tags: [gatsby] (a list), you get conflicts. Two defenses: use the same shape everywhere, and declare types explicitly with createSchemaCustomization:

JavaScript
// gatsby-node.js (real Gatsby, read-only)
exports.createSchemaCustomization = ({ actions }) => {
  actions.createTypes(`
    type MarkdownRemark implements Node {
      frontmatter: Frontmatter
    }
    type Frontmatter {
      title: String!
      date: Date @dateformat
      updated: Date @dateformat
      tags: [String!]
      draft: Boolean
    }
  `)
}

Now updated is always queryable (it is null when missing) and tags is always a list.

Tag pages

Query the distinct tag values with group, which collects nodes by a field:

JavaScript
// gatsby-node.js (real Gatsby, read-only)
exports.createPages = async ({ graphql, actions }) => {
  const result = await graphql(`
    {
      tagsGroup: allMarkdownRemark(filter: { frontmatter: { draft: { ne: true } } }) {
        group(field: { frontmatter: { tags: SELECT } }) {
          fieldValue
          totalCount
        }
      }
    }
  `)
  result.data.tagsGroup.group.forEach(({ fieldValue }) => {
    actions.createPage({
      path: `/tags/${fieldValue}/`,
      component: require.resolve("./src/templates/tag.js"),
      context: { tag: fieldValue },
    })
  })
}

The template then filters with the context variable:

JSX
// src/templates/tag.js (real Gatsby, read-only)
export const query = graphql`
  query ($tag: String!) {
    allMarkdownRemark(filter: { frontmatter: { tags: { in: [$tag] } } }) {
      nodes { id fields { slug } frontmatter { title } }
    }
  }
`

Tag values go in a URL, so slugify them (lowercase, no spaces): "Web Performance" becomes web-performance. Keep a lookup of the original label if you want to display it.

Pagination

To split N posts into pages of perPage each, create ceil(N / perPage) pages. Each one gets skip and limit in its context, which the template passes to the query:

JSX
// real Gatsby, read-only
export const query = graphql`
  query ($skip: Int!, $limit: Int!) {
    allMarkdownRemark(sort: { frontmatter: { date: DESC } }, skip: $skip, limit: $limit) {
      nodes { id frontmatter { title } }
    }
  }
`

The first page lives at /blog/, the others at /blog/2/, /blog/3/, and so on. The next stand-in does the math, including the previous and next links.

JS Stand-in: pagination math

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

No output.

Notice that an empty blog creates zero pages; handle this case so /blog/ does not 404 (create the first page anyway with Math.max(1, ...)).

Grouping stand-in

The group field is just a reduce over the posts. This imitation returns tags with counts, sorted by popularity, and filters out drafts, like the query above.

JS Stand-in: group posts by tag

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

No output.

A simple related-post rule: rank other posts by the number of shared tags. Compute it in createPages, store the ids in the page context, and fetch them with filter: { id: { in: $relatedIds } }.

Drafts

Use a draft: true front matter flag and filter it out in production queries (filter: { frontmatter: { draft: { ne: true } } }). In development you can include drafts by checking process.env.NODE_ENV in gatsby-node.js and building the filter conditionally.

Common mistakes

  • Different shapes of the same field across files; declare types explicitly.
  • Using raw tag text in URLs without slugifying.
  • Forgetting Int! types for $skip and $limit.
  • Building pagination from a list that includes drafts.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How many pages are needed for 23 posts at 10 per page?

    ceil(23 / 10) is 3.
  2. 2. Which GraphQL feature collects posts by a field value, for example tags?

    group returns fieldValue and the nodes (or totalCount) for each distinct value.
  3. 3. How do you pass the current tag to the tag template query?

    createPage context values become GraphQL variables.
  4. 4. What does createSchemaCustomization help with?

    Explicit types prevent missing-field and mixed-type errors.

Summary

  • Keep front matter consistent and declare types in createSchemaCustomization.
  • Use group to find tags, then createPage per tag with a tag in the context.
  • Pagination creates ceil(total / perPage) pages with skip and limit.
  • Slugify tag names, exclude drafts and handle the empty case.

Next: SEO, Head API, sitemap and RSS