metalsmith-yearly-pagination v4.0.2

metalsmith-yearly-pagination

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!

Usage

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

blog.md

---
template: TEMPLATE-NAME.EXT
paginate: posts
---

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

const Metalsmith  = require('metalsmith');
const collections = require('metalsmith-collections');
const pagination  = require('metalsmith-yearly-pagination');

Metalsmith(__dirname)
  .use(collections({
    blog: {
      pattern: 'content/blog/*.md',
      sortBy: 'date',
      reverse: true
    }
  }))
  .use(pagination({
    path: 'blog/page'
  }))
  .use(templates('ENGINE-NAME'))
  // ...
  .build();

Options

Templates

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:

You can then use this info in your template.

<h1>Posts from {{pagination.year}}</h1>
{{#each collections.blog.posts}}
  <li class="post">
    <h2 class="entry-title">
      <a href="{{ path }}" rel="bookmark">{{ title }}</a>
    </h2>
    <article class="entry-summary">
      {{ excerpt }}
    </article>
    <footer>
      <a href="{{ path }}" class="button">Read More</a>
    </footer>
  </li>
{{/each}}

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

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

Advanced usage

It's made for extensibility by allowing you to pass a options.iteratee function which are called for every collection post.

Example below illustrates this by displaying the excerpt of the top 10 posts per year, follow by posts only listed by its title.

Metalsmith setup

const Metalsmith  = require('metalsmith');
const collections = require('metalsmith-collections');
const pagination  = require('metalsmith-yearly-pagination');

Metalsmith(__dirname)
  .use(collections({
    blog: {
      pattern: 'content/blog/*.md',
      sortBy: 'date',
      reverse: true
    }
  }))
  .use(pagination({
    path: 'blog/page',
    iteratee: (post, idx) => ({
      post,
      displayExcerpt: idx < 10,
    })
  }))
  .use(templates('ENGINE-NAME'))
  // ...
  .build();

Template

{{#each collections.blog.posts}}
  <li class="post">
    <h2 class="entry-title">
      <a href="{{ post.path }}" rel="bookmark">{{ post.title }}</a>
    </h2>
    {{#if displayExcerpt}}
      <article class="entry-summary">
        {{ post.excerpt }}
      </article>
    {{/if}}
    <footer>
      <a href="{{ post.path }}" class="button">Read More</a>
    </footer>
  </li>
{{/each}}

Contributing

This is an OPEN Open Source Project. This means that:

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

See the contribution guide for more details.

This project was originally a fork of the metalsmith-paginate.