Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Metalsmith Pagination

NPM version NPM downloads Build status Test coverage

A Metalsmith plugin for paginating arrays and collections.


npm install metalsmith-pagination --save


To paginate an array of files, you need to have a property that points to the location of the collection you want to paginate. The value should be an options object that will be used to initialize the plugin.

P.S. Make sure the pagination middleware is defined after the files array exists, but before the template middleware renders.


Install via npm and then add metalsmith-pagination to your metalsmith.json:

  "plugins": {
    "metalsmith-pagination": {
      "collections.articles": {
        "perPage": 5,
        "template": "index.jade",
        "first": "index.html",
        "path": "page/:num/index.html",
        "filter": "private !== true",
        "pageMetadata": {
          "title": "Archive"


Install via npm, require the module and .use the result of the function.

var pagination = require('metalsmith-pagination')

  'collections.articles': {
    perPage: 5,
    template: 'index.jade',
    first: 'index.html',
    path: 'page/:num/index.html',
    filter: function (page) {
      return !page.private
    pageMetadata: {
      title: 'Archive'


  • perPage The number of files per page (default: 10).
  • first An optional path to use in place of the page one (E.g. Render as the homepage index.html, instead of page/1/index.html).
  • path The path to render every page under. Interpolated with the pagination object, so you can use :name, :num or :index.
  • filter A string or function used to filter files in pagination.
  • pageMetadata The metadata to merge with every page.
  • noPageOne Set to true to disable rendering of page one, useful in conjunction with first (default: false).
  • groupBy Set the grouping algorithm manually (default: paginated by perPage). Useful for paginating by other factors, like year published (E.g. date.getFullYear()).
  • empty Allows empty pages for collections. This will also be used as the file passed to groupBy to get the page name.
  • template The template metadata for metalsmith-templates.
  • layout The layout metadata for metalsmith-layouts.
  • pageContents Set the contents of generated pages (default: Buffer.from('')). Useful for metalsmith-in-place (especially with pageMetadata).

Page Metadata

The pageMetadata option is optional. The object passed as pageMetadata is merged with the metadata of every page generated. This allows you to add arbitrary metadata to every page, such as a title variable.

Template Usage

Within the template you specified, you will have access to pagination specific helpers:

  • pagination.num The current page number.
  • pagination.index The current page index (num - 1).
  • pagination.getPages(num) Get an array of num pages with the current page as centered as possible
  • The page name from groupBy. If no groupBy was used, it is the current page number as a string.
  • pagination.files All the files to render in the current page (E.g. array of x articles).
  • pagination.pages References to every page in the collection (E.g. used to render pagination numbers).
  • The next page, if it exists.
  • pagination.previous The previous page, if it exists.
  • pagination.first The first page, equal to pagination.pages[0].
  • pagination.last The last page, equal to pagination.pages[pagination.pages.length - 1].

For example, in Jade:

block content
  each file in pagination.files
          time.timestamp( moment('MMMM D, YYYY')
          a(href='/' + file.path)= file.title
      section.content-article!= file.snippet
    if pagination.previous
      a.btn.pull-right(href='/' + pagination.previous.path)
        | Newer  
      a.btn.pull-left(href='/' +
        |   Older