metalsmith-perma

metalsmith-perma

metalsmith-perma is an alternative to metalsmith-permalinks for applying permalinks to your static content.

Installation

With npm:

npm install metalsmith-perma

With yarn:

yarn add metalsmith-perma

Usage

var metalsmith = require('metalsmith');
var permalinks = require('metalsmith-perma');

metalsmith(__dirname)
  .use(permalinks({
    pattern: ':title'
  }));

metalsmith-perma uses slugify for converting patterns to permalinks. You can pass options to slugify with an options parameter:

metalsmith.use(permalinks({
  pattern: ':title'.
  options: {
    replacement: '-', // replace spaces with replacement
    remove: null,     // regex to remove characters
    lower: true       // result in lower case
  }
}));

Slugify options defaults to { lower: true, remove: /!$'"*+,;=?%/ }, but you can view a full list of options.

Dates

Dates are formatted using date-fns/format.

metalsmith.use(permalinks({
  pattern: ':date/:title',
  date: 'YYYY'
}));

Overriding Permalinks

Permalinks can be defined in the metalsmith pipeline, or in frontmatter.

---
title: Page Title
permalink: custom-path/to/:title
---

Skipping Permalinks

Permalinks can be skipped in individual files by including permalink: false.

---
title: Page Title
permalink: false
---

Matching Patterns

metalsmith-perma allows you to have multiple sets of matching patterns against matching metadata. Works well with metalsmith-collections

metalsmith
  .use(collections({
    collections({
      posts: {
        pattern: 'posts/*.md'
      }
    })
  })
  .use(permalinks({
    match: { collections: ['post'] },
    pattern: 'posts/:title'
  }));

Along with pattern matching, you can create different matching patterns of permalinks by including multiple sets of options along with a default flag to mark the default match.

metalsmith.use(permalinks([
  {
    match: { collections: ['post'] },
    pattern: 'posts/:title'
  },
  {
    match: { collections: ['authors'] },
    pattern: 'authors/:name'
  },
  {
    default: true,
    pattern: ':title'
  }
]));

License

MIT