metalsmith-hrefdeprecated

A Metalsmith plugin to insert files URL in metadata

Usage no npm install needed!

<script type="module">
  import metalsmithHref from 'https://cdn.skypack.dev/metalsmith-href';
</script>

README

metalsmith-href

A Metalsmith plugin to insert files URL in metadata

CircleCI Codecov NPM Latest Master

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

  1. Install this plugin (see Installing)
  2. Add it to your Metalsmith build file or configuration
  3. Use the href property in your templates (see examples below)
  4. (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": {}
  }]
}

Contributing

If you'd like to contribute, please fork the repository and use a feature branch. Issues and pull requests are warmly welcome.

Links and references

Related

Dependencies

License

This software is free software licensed under the MIT License. See LICENSE.MD