node package manager


Metalsmith Collections Paginate

NPM version Build status Test coverage Gittip

A Metalsmith plugin for paginating collections.

You should use metalsmith-pagination instead!


npm install metalsmith-collections-paginate --save


To paginate a collection of files, you need to add a property with the same collection name to the options object that you use to initialize the plugin.


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

  "plugins": {
    "metalsmith-collections-paginate": {
      "articles": {
        "perPage": 5,
        "template": "index.jade",
        "first": "index.html",
        "path": "page/:num/index.html"


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

var paginate = require('metalsmith-collections-paginate');
  articles: {
    perPage: 5,
    template: 'index.jade',
    first: 'index.html',
    path: 'page/:num/index.html',
    pageMetadata: {
      title: 'Articles Archive'

The pageMetadata option is optional. The object passed as pageMetadata is used as the base for any created pages metadata. This allows for adding arbitrary metadata to the created pages like a page title variable, allowing for more reuse of list page templates.


Within the template file you specified, you will have access to a bunch of pagination specific variables:

  • pagination.num - The current page number.
  • pagination.files - All the files on the current page, iterate over this to render the page.
  • - The name of the current collection.
  • pagination.pages - A link to all the pages in the collection (aliased under collection.pages).
  • - Links to the next page file, if it exists.
  • pagination.previous - Links to the previous page file, if it exists.