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


This plug-in makes metalsmith-collections "paginatable". it does so by creating virtual files which contain the information about the collection as well as the previous and next page.

You must use this in conjunction with metalsmith-collections!


Firstly you must create a file that contains the information over which collection you want to paginate and the template name:

paginate: posts

Note: if you give the page a title and use the metalsmith-permalinks plug-in you might get some weird result.

Then use your collections as usual and call paginate().

var Metalsmith  = require('metalsmith'),
    collections = require('metalsmith-collections'),
    paginate    = require('metalsmith-paginate'),
    // ...

        posts: {
            pattern: 'content/posts/*.md',
            sortBy: 'date',
            reverse: true
        perPage: 10,
        path: "blog/page"
    // ...


name description
perPage The number of items to be displayed per page
path The path were the files will be outputted to. Appended with "-$NUM.html" where $NUM is the page number. So "blog/page" would for example result in the second page being rendered as blog/page-2.html. You can also use the placeholder ':collection' to insert the name of the collection.


The pagination info won't be of any use to you if you don't render it. Each (virtual) pagination file will contain a new object under the key "pagination" which contains the following info:

name description
num The page number
total The total number of pages
start The start index
end The end index
prev The previous page object
next The next page object

You can then use this info in your template. Here's an example using Handlebars with a custom limit helper (which can be found here).

{{#each (limit collections.posts this.pagination.end this.pagination.start)}}
    <li class="post">
        <h2 class="entry-title">
            <a href="{{ this.path }}" rel="bookmark">{{ this.title }}</a>
        <article class="entry-summary">
            {{{ this.excerpt }}}

            <a href="{{ this.path }}" class="button">Read More</a>

{{#if this.pagination}}
    <nav class="pagination">
            <a href="{{}}">&lt; Prev</a>
        {{#if this.pagination.prev}}
            <a href="{{this.pagination.prev.path}}">Next &gt;</a>

Note: This example also uses the metalsmith-permalinks plug-in


A simple plugin that uses metalsmith-collections to create a paginated collection







No packages published