Metalsmith-href NPM

metalsmith-href

A Metalsmith plugin to insert files URL in metadata

This plugin inserts absolute URLs to files in the metadata. This is useful to fill href attributes in templates. Used with metalsmith-link, it is possible to create links between files without having to worry about their location in the destination folder.

Getting started

Install this plugin (see Installing)
Add it to your Metalsmith build file or configuration
Use the href property in your templates (see examples below)
(optional) customize the name of the href property (see Configuring)

Example layout

See metalsmith-link to fill the links property.

<!DOCTYPE html>
<html>
  <head>
    <title>{{ title }}</title>
  </head>
  <body>
    <header>
      <h1>{{ title }}</h1>
    </header>
    <nav>
      <ul>
        <li><a href="{{ href }}">Useless link to this page</a></li>
        {% for link in links %}
        <li><a href="{{ link.href }}">{{ link.title }}</a></li>
        {% endfor %}
      </ul>
    </nav>
    <main>
      {{ contents | safe }}
    </main>
    <footer>
      <hr />
      Licensed under CC-BY-SA
    </footer>
  </body>
</html>

Installing

With npm installed, run

$ npm install metalsmith-href

For static websites, some prefer to specificy --save-dev to npm install as the distributed website does not actually require this plugin as a dependency.

Configuring

Since Metalsmith follows a Pipeline pattern, the step at which plugins run is important. This plugin should ideally run just before the layout step.

There are a few options:

name	default	description
property	href	name of the metadata property to create/replace
basehref	empty	base URL to preprend (e.g. https://my-site.tld)
index	index.html	name of the directory index file to strip (e.g. for links like `/` instead of `/index.html`)

Example build file with options

// ...
Metalsmith(__dirname)
    .use(link())
    .use(markdown())
    .use(href({ property: "url", basehref: "https://my-site.tld", index: "index.htm" }))
    .use(layouts())
    .build(function (err) {
        if (err) throw err;
    });

Example configuration with options

{
  "source": "src",
  "destination": "build",
  "plugins": [{
    "metalsmith-link": {},
    "metalsmith-markdown": {},
    "metalsmith-href": {
      "property": "url",
      "basehref": "https://my-site.tld",
      "index": "index.htm"
    },
    "metalsmith-layouts": {}
  }]
}