Metalsmith-link NPM

metalsmith-link

A Metalsmith plugin to link files in metadata

This plugin transforms named references to files in the metadata to direct references. This is useful to keep track of a file, from the source folder to the destination folder. Potential uses include:

multiple part blog articles
canonical links
hreflang links

What do you use it for? Please comment.

Getting started

Install this plugin (see Installing)
Add it to your Metalsmith build file or configuration
Add a links property in your source files frontmatter metadata
Use the links property in your layouts to access other files metadata
(optional) customize the name of the links property (see Configuring)

Example source files

src/my-blog-article-part-1.md

---
title: My Blog Article - Part 1
links:
- my-blog-article-part-2.md
- my-blog-article-part-3.md
layout: my-layout.njk
---

Hello, World!

...along with my-blog-article-part-2.md and my-blog-article-part-3.md

Example layout file

layouts/my-layout.njk

<!DOCTYPE html>
<html>
  <head>
    <title>{{ title }}</title>
  </head>
  <body>
    <header>
      <h1>{{ title }}</h1>
    </header>
    {% if links %}
    <aside>
      <ul>
        {% for link in links %}
        <li>{{ link.title }}</li>
        {% endfor %}
      </ul>
    </aside>
    {% endif %}
    <main>
      {{ contents | safe }}
    </main>
    <footer>
      <hr />
      Licensed under CC-BY-SA
    </footer>
  </body>
</html>

Example build script

index.js

var Metalsmith = require("metalsmith");
var link = require("metalsmith-link");
var markdown = require("metalsmith-markdown");
var layouts = require("metalsmith-layouts");

Metalsmith(__dirname)
    .use(link())
    .use(markdown())
    .use(layouts())
    .build(function (err) {
        if (err) throw err;
    });

Example output file

build/my-blog-article-part-1.html

<!DOCTYPE html>
<html>
  <head>
    <title>My Blog Article - Part 1</title>
  </head>
  <body>
    <header>
      <h1>My Blog Article - Part 1</h1>
    </header>
    <nav>
      <ul>
        <li>My Blog Article - Part 2</li>
        <li>My Blog Article - Part 3</li>
      </ul>
    </nav>
    <main>
      Hello, World!
    </main>
    <footer>
      <hr />
      Licensed under CC-BY-SA
    </footer>
  </body>
</html>

If you prefer diagrams...

Before	After

Since Metalsmith follows a Pipeline pattern, the step at which plugins run is important.

This plugin will convert named references (string values) to direct (object) references, based on the path of other files at the step at which it runs. Hence, if you want to be able to reference files using their path in the source directory, this plugin should run before any transformation that renames those files (e.g. metalsmith-layouts).

Alternatively, if you can predict the path of files at a certain step, and you prefer to name references accordingly, this plugin should run after this specific step.

Installing

With npm installed, run

$ npm install metalsmith-link

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

There is only one option: property (defaults to links). It can be any string that is a valid key for a frontmatter property, and specifies the metadata key that this plugin will replace.

Example build file with options

// ...
Metalsmith(__dirname)
    .use(link())
    .use(markdown())
    .use(layouts({ property: "hrefs" }))
    .build(function (err) {
        if (err) throw err;
    });

Example configuration with options

{
  "source": "src",
  "destination": "build",
  "plugins": [{
    "metalsmith-link": {
      "property": "hrefs"
    },
    "metalsmith-markdown": {},
    "metalsmith-layous": {}
  }]
}

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

Source code: https://github.com/pierresenechal/metalsmith-link
Issue tracker: https://github.com/pierresenechal/metalsmith-link/issues

Dependencies

Metalsmith: https://github.com/segmentio/metalsmith

License

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

link metadata metalsmith metalsmith-plugin

debug pkginfo

1.0.2

6 years ago

1.0.0

6 years ago