Dynamic pages#

In previous chapters, we learned how:

  • Create static pages

  • Fetch data from external sources

  • Query data and show it in pages

We could potentially build our static websites just with that information.

The only problem is that we need to manually create every single page that we need.

The last missing part in building a static website with GatsbyJS is to programmatically generate these pages from data.

As we have seen in the Pages chapter, at build time GatsbyJS maps every page with an URL that is its filename. If we want to programmatically generate static pages, we are not going to have different page components (one for each node), but only GraphQL nodes. We need to provide some additional information in nodes to allow GatsbyJS to generate the correct pages and URLs.

In particular we need to add a "slug" or "path" attribute to the node.


A lot of source plugins automatically add this information in nodes, like CMS plugins.

The GatsbyJS building stack has a sequence of steps that perform different actions:

  • Read the configuration to load the list of plugins

  • Initialize the cache (to avoid re-fetch untouched data)

  • Pull the data and preprocess it in a GraphQL schema

  • Create pages (from /pages folder or from plugins)

  • Extract and run GraphQL queries and replace their values in pages

  • Write out the pages as static HTML pages

GatsbyJS provides a rich set of "lifecycle APIs" to hook into every step and perform some customizations. In this chapter we are going to use two of these APIs, which are the most used in plugins:

  • onCreateNode: called by GatsbyJS whenever a node is created or updated, so we can edit the current node before storing it into GraphQL

  • createPages: step that creates a page.

To implement an API, we need to export a function with the same name of the API in a file called gatsby-node.js.

Let us start with the first one, and export a function called onCreateNode:

exports.onCreateNode = ({ node }) => {

This function is called whenever a node is created.

If we restart the server now, we will see that in the console we will have the types of every node. We want to add a slug only for nodes generated by the MarkdownRemark plugin.

We need to filter them by type. To generate the slug for this node, we could use a helper funcion from gatsby-source-filesystem that is made for this purpose: createFilePath.


If you remember, Remark nodes are built on top of filesystem nodes.

Finally we need to add the slug attribute to the node. Nodes can be directly modified only by the plugins that created them. Other plugins can add new fields to the nodes only with a specific function called createNodeField (for security reasons).

And finally, our onCreateNode function will be similar to this:

 5// complete example
 6const { createFilePath } = require(`gatsby-source-filesystem`)
 7const path = require(`path`)
 9exports.onCreateNode = ({ node, getNode, actions }) => {
10  const { createNodeField } = actions
11  if (node.internal.type === `MarkdownRemark`) {
12    const slug = createFilePath({ node, getNode, basePath: `blog` })
13    createNodeField({
14      node,
15      name: `slug`,
16      value: slug,
17    })
18  }

If we restart the server and try to query the data, we will see the slug under the fields attribute.

Now that we have all the information, we need to create pages.

As mentioned in the introduction, to create a page we need to query data with GraphQL and then map the results into a page.

To do this, we need to export the other mentioned function (createPages) in gatsby-node.js file:

21exports.createPages = ({ graphql, actions }) => {
22    const { createPage } = actions
23    return new Promise((resolve, reject) => {
24      graphql(`
25        {
26          allMarkdownRemark {
27            edges {
28              node {
29                fields {
30                  slug
31                }
32              }
33            }
34          }
35        }
36      `).then(result => {
37        result.data.allMarkdownRemark.edges.forEach(({ node }) => {
38          createPage({
39            path: node.fields.slug,
40            component: path.resolve(`./src/templates/blog-post.js`),
41            context: {
42              slug: node.fields.slug,
43            },
44          })
45        })
46        resolve()
47      })
48    })
49  }

What can we see here?

First of all we perform a GraphQL query, and we iterate through the results to create a new page.

The method createPage is a helper method that GatsbyJS uses to generate dynamic pages.

It takes 3 parameters:

path: the slug value.

This is used to generate the URL where we can access the current page.

component: the template used to populate a blog post page.

It is similar to a page component (we will see it shortly).

context: we can pass a list of variables that can be used by the queries into page components (not StaticQuery) to fetch information about the current node.

A this point we create the blog-post.js template file to end our setup:

import React from "react"
import { graphql } from "gatsby"
import Layout from '../components/layout'

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

export const query = graphql`
  query($slug: String!) {
    markdownRemark(fields: { slug: { eq: $slug } }) {
      frontmatter {

This is similar to a simple page component, except for GraphQL query. We need to fetch data for a specific node. To do this, we can use the slug value to filter only desired node.


We can filter with almost every node attribute, but it is always better use uniques values like id or slug.


dangerouslySetInnerHTML is a helper function of ReactJS that allows to insert some not-reactish HTML into a component.

If we restart the server, we can now directly access the pages that were automatically created.


To easily get a list of generated URLs, try to access a random page like http://localhost:8000/asdf. The default NotFound page will offer alternative URLs.

Last thing that we could do is to link them in our index.js page:

import React from 'react'
import { Link } from 'gatsby'
import { graphql } from 'gatsby'

import Layout from '../components/layout'

const IndexPage = ({ data }) => (
      <h1>A blog about The conference</h1>
      <h4>{data.allMarkdownRemark.totalCount} Posts</h4>
      {data.allMarkdownRemark.edges.map(({ node }) => (
        <div key={node.id}>
          <Link to={node.fields.slug}>
              {node.frontmatter.title}{" "}
                {"- "}{node.frontmatter.date}

export const query = graphql`
  query {
    allMarkdownRemark {
      edges {
        node {
          frontmatter {
            date(formatString: "DD MMMM, YYYY")
          fields {

export default IndexPage