Gatsby Page Ordering

It’s often the case that we want pages on a site to be presented in a specific order. It’s possible to do this systematically by sorting on some existing aspect of the content (for example, sort alphabetically by page title) or by introducing a page attribute that’s specifically intended for sorting.

Default Page Order

We’ll build on the basic AsciiDoc site from a previous post. I’ve added a few more pages to the site to make things more interesting.

The order of the content feels a little random, right? And it is. There’s no systematic order to it. We’ll need to fix that!

🚀 TL;DR Show me the code. Look at the 10-order-default branch. This site is deployed here.

Sort using GraphQL

One option is to sort in the GraphQL query. For example, one might order by document title.

query order {
  allAsciidoc(sort: { document: { title: ASC } }) {
    nodes {
      document {
        title
      }
    }
  }
}

You can apply this to the order of pages on the landing page by updating the GraphQL query in src/pages/index.js.

Well, there’s certainly an order to the pages now. But perhaps not a very meaningful order? Ideally I’d like to have those pages in an order which conveys a logical development of topics.

🚀 TL;DR Show me the code. Look at the 11-order-document-title branch. This site is deployed here.

Explicit Order Attribute

We can achieve granular ordering of pages by adding a page attribute, page-order. The value of this attribute is an integer and the pages will be ordered according to it. The head of a document with the page-order attribute might look like this:

= What is Gatsby?
Some Fictional Dude <some-fictional-dude@gmail.com>
v2.0, October 2023: Rewritten for version 2
:description: An explanation of Gatsby.
:page-version: 0.3, 1.0, 1.1, 1.2
:page-order: 10
:page-permalink: d2b6d682

It’s good practice to stagger the order integers assigned to each of the pages. For example, start off by assigning the pages 10, 20, 30… etc. This allows you to painlessly insert new pages later on.

Here are the values which I assigned to the page-order attribute for each of the content pages:

Now we can use this attribute in our GraphQL query, which might be updated like this:

query order {
  allAsciidoc(sort: {pageAttributes: {order: ASC}}) {
    nodes {
      document {
        title
      }
    }
  }
}

Once again this change is applied to the GraphQL query in src/pages/index.js.

🚀 TL;DR Show me the code. Look at the 12-order-page-attribute branch. This site is deployed here.

Conclusion

Using a combination of GraphQL queries and page attributes it’s possible to sort your pages as required. This can be done systematically using an existing page attribute or by introducing a page attribute which explicitly asserts page order.