An alternative plugin for Metalsmith for creating permalinks
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
test
.babelrc
.editorconfig
.eslintignore
.eslintrc
.gitignore
.travis.yml
license
package-lock.json
package.json
readme.md replace invalid characters in permalink urls Dec 23, 2017
rollup.config.js

readme.md

metalsmith-perma Build Status Coverage Status npm

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