This package has been deprecated

    Author message:

    No longer maintained; Migrate to the following package: @metalsmith/permalinks

    metalsmith-permalinks

    2.2.0 • Public • Published

    metalsmith-permalinks

    npm version code style: prettier metalsmith: plugin

    Build Status

    A Metalsmith plugin that applies a custom permalink pattern to files, and renames them so that they're nested properly for static sites (converting about.html into about/index.html).

    Installation

    $ npm install metalsmith-permalinks
    

    Usage

    var Metalsmith = require('metalsmith');
    var permalinks = require('metalsmith-permalinks');
     
    var metalsmith = new Metalsmith(__dirname).use(
      permalinks({
        pattern: ':title'
      })
    );

    The pattern can contain a reference to any piece of metadata associated with the file by using the :PROPERTY syntax for placeholders.

    If no pattern is provided, the files won't be remapped, but the path metadata key will still be set, so that you can use it for outputting links to files in the template.

    The pattern can also be a set as such:

    var Metalsmith = require('metalsmith');
    var permalinks = require('metalsmith-permalinks');
     
    var metalsmith = new Metalsmith(__dirname).use(
      permalinks({
        // original options would act as the keys of a `default` linkset,
        pattern: ':title',
        date: 'YYYY',
     
        // each linkset defines a match, and any other desired option
        linksets: [
          {
            match: { collection: 'blogposts' },
            pattern: 'blog/:date/:title',
            date: 'mmddyy'
          },
          {
            match: { collection: 'pages' },
            pattern: 'pages/:title'
          }
        ]
      })
    );

    Dates

    By default any date will be converted to a YYYY/MM/DD format when using in a permalink pattern, but you can change the conversion by passing a date option:

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

    It uses moment.js to format the string.

    Custom 'slug' function

    If you do not like filenames, you can replace slug function. For now only js version of syntax is supported and tested.

    metalsmith.use(
      permalinks({
        pattern: ':title',
        slug: require('transliteration').slugify
      })
    );

    There are plenty on npm for transliteration and slugs. https://www.npmjs.com/browse/keyword/transliteration, better than default slug-component.

    Relative Files

    When this plugin rewrites your files to be permalinked properly, it will also duplicate sibling files so that relative links like /images/cat.gif will be preserved nicely. You can turn this feature off by setting the relative option to false.

    For example for this source directory:

    src/
      css/
        style.css
      post.html
    

    Here's what the build directory would look like with relative on:

    build/
      post/
        index.html
        css/
          style.css
      css/
        style.css
    

    And here's with relative off:

    build/
      post/
        index.html
      css/
        style.css
    

    relative can also be set to folder, which uses a strategy that considers files in folder as siblings if the folder is named after the html file.

    For example using the folder strategy with this source directory:

    src/
      post.html
      post/
        image.jpg
    

    Here's what the build directory would look like with relative set to folder:

    build/
        index.html
        image.jpg
    

    Skipping Permalinks for a file

    A file can be ignored by the metalsmith-permalinks plugin if you pass the permalink: false option to the yaml metadata of a file. This is useful for hosting a static site on AWS S3, where there is a top level error.html file and not an error/index.html file.

    For example, in your error.md file:

    ---
    template: error.html
    title: error
    permalink: false
    ---

    Slug Options

    slug is used for slugifying strings and it's set to lower-case mode by default.

    You can pass custom slug options:

    metalsmith.use(
      permalinks({
        slug: {
          replacement: '_',
          lower: false
        }
      })
    );

    The following makes everything snake-case but allows ' to be converted to -

    metalsmith.use(
      permalinks({
        slug: {
          remove: /[^a-z0-9]+/gi,
          lower: true,
          extend: {
            "'": '-'
          }
        }
      })
    );

    Overriding the permalink for a file

    Using the permalink property in a file's front-matter, its permalink can be overridden. This can be useful for transferring projects over to Metalsmith where pages don't follow a strict permalink system.

    For example, in one of your pages:

    ---
    title: My Post
    permalink: "posts/my-post"
    ---

    Overriding the default index.html file

    Use indexFile to define a custom index file.

    metalsmith.use(
      permalinks({
        indexFile: 'alt.html'
      })
    );

    Ensure files have unique URIs

    Use unique: true or provide a function to customise the URI when clashes occur.

    To automatially add -1, -2, etc. to the end of the URI to make it unique:

    metalsmith.use(
      permalinks({
        unique: true
      }
    );

    Provide your own function to create a unique URI:

    metalsmith.use(
      permalinks({
        unique: uniqueFunction
      }
    );

    Where uniqueFunction takes the form:

    const uniqueFunction = (path, files, filename, options) => {
      return `path/index.html`;
    };

    Error when there's a URI conflict

    When URI when clashes occur, the build will halt with an error stating the target file conflict.

    metalsmith.use(
      permalinks({
        duplicatesFail: true
      }
    );

    Note: This will not work if you've provided your own unique function.

    CLI

    You can also use the plugin with the Metalsmith CLI by adding a key to your metalsmith.json file:

    {
      "plugins": {
        "metalsmith-permalinks": {
          "pattern": ":title"
        }
      }
    }

    History

    History

    License

    MIT

    Keywords

    none

    Install

    npm i metalsmith-permalinks

    DownloadsWeekly Downloads

    1,763

    Version

    2.2.0

    License

    MIT

    Unpacked Size

    32 kB

    Total Files

    100

    Last publish

    Collaborators

    • f2prateek
    • ianstormtaylor
    • lambtron
    • segmentio