Indexes

Indexes allow you to create a series of paginated results that list other pages or array data. For example, you could use an index to list links to all of your blog posts or product pages.

Indexes can be populated in three different ways. You can use any of these options alone or mix them together.

1. Add pages with specific tags using the tags option.
2. Add pages with URLs that match a glob pattern with the glob option.
3. Add all the items in an array using the list option.

Create an index page using index in your template data.

export default {
  index: {
    tags: ["posts"],
    glob: "/more/*",
    list: [{ other: "data" }],
  },
}

See An example index for a working example.

Options

tags

Use tags to add any pages that include a specific tag. Tags should be an array of strings, just like template tags.

glob

Use glob to add any pages with a URL that matches a glob pattern. Note that all page URLs contain a leading slash, so your pattern should too.

list

You can add any arbitrary array of items with list. This is useful when you want to create pages indexing a series of items that don’t have any associated page.

size

When the number of items in the list is greater than size, Night Owl will chunk the results into different pages. For example, if you have 15 items in an array and the size is 10, then Night Owl generates two pages. The first has 10 items and the second page has the last five items.

slug

The slug option is used to generate the URL for pages that follow the first page.

The base URL is taken from the template, followed by the slug, with the page number at the end. The default slug is "page". For example, if your index will generate three pages and the slug is "more", Night Owl uses posts/more/1 for the second page and posts/more/2 for the third page.

If you need more control over the URL format, use a function instead. For example, to use posts/page-0/, posts/page-1/, …, you could use the function below.

export default {
  index: {
    slug: function (url, index) {
      return `${url}/page-${index}/`
    },
  },
}

layout

Use this option if you want to specify a different layout to the one defined in the template. This can be useful when you also have pages data, and you only want the pages to inherit the template layout.

filter

If you want to remove some items from the list of results, use a filter function. The function is called on each item in the array using Array.prototype.filter().

Generated data

meta.index

In addition to the meta data generated for a template, index pages are provided with meta.index data.

The meta.index.items array lists the items on the current index page that have been added with the tags, glob and list options.

When you use the size option, an index may generate multiple pages of results. Links to those pages can also be accessed with meta.index.

Use meta.index.prev and meta.index.next to link to the previous and next pages. To access other index pages, use the meta.index.pages array. Night Owl also provides the current index page number as meta.index.page.

{
  meta: {
    index: {
      // All the items on this index page
      items: [...],

      // The index of the current page
      page: 0,

      // The first page has no previous link
      prev: undefined,

      // The data for the next index page
      next: {
        src: "src/posts.template.js",
        dist: "dist/posts/page/1/index.html",
        url: "/posts/page/1",
      },

      // All pages in this index. For example,
      // if you have 15 blog posts and `size`
      // is set to 5, there will be 3 pages.
      pages: [...]
    }
  },
}

Note that meta.index.prev is undefined for the first page, and meta.index.next is undefined for the last page in the index results. If you use these variables in a layout, first check whether they are available.

nav
  if meta.index.prev
    a(href=meta.index.prev.url) Previous

  if meta.index.next
    a(href=meta.index.next.url) Next

Empty indexes

Night Owl will still generate an index page when there are no items that match the tags, glob and list options.

Indexes and collections

Index pages can use other pages tags to generate new pages. To avoid creating a circular dependency with collections, index pages cannot be tagged like other template pages. However, index pages do appear in the special meta.collections.all array along with all the other pages of your site.