metalsmith-relative-links

Metalsmith plugin that adds functions to the metadata that assist with creating links to other resources.

What It Does

Each source file will have a link() function added to the metadata, allowing easier link generation. There are also helper functions: link.from(), link.to(), and link.resolve(). One would use these functions in templates to generate links to other resources. This is an extremely handy plugin when you have a file tree in the metadata. It works great with metalsmith-hbt-md and metalsmith-ancestry. Those two plugins will process Mustache templates in markdown and add a file hierarchy to the metadata. It's useful for creating subpage listings:

Now you simply add another page to your sources and rerun Metalsmith. Your index page is updated automatically.

link(from, to)

Returns a relative link between from and to. If from is "tools/index.html" and to is "tools/hammers/claw.html", the link returned would be "hammers/claw.html".

The from and to arguments are resolved to strings by link.resolve().

Options also control how the links are generated. See more about that in the Usage section.

link.from(to)

Shorthand to create a link from the current file object to a given destination. More details listed in link() and link.resolve().

link.resolve(what)

This changes what into a string. It can be any of the following.

• File object. This is looked up and its key is used as the resolved value. This lets you link from one file object to another without knowing where in your directory hierarchy they are located.
• Relative paths, such as "..", "folder/file.html". These are resolved against the current file object's location so they act exactly as you would imagine.
• Absolute paths, such as "/filename.html" or "/folder/file.html". These are resolved against the root.
• Empty string. Resolved as a link to the root and is functionally the same as "/".

When none of these match, an error is thrown.

link.to(from)

Shorthand to create a link from the specified resource to the current file object. Check out link() and link.resolve() for further information.

Installation

npm can do this for you.

npm install --save metalsmith-relative-links

Usage

Include this like you would include any other plugin. Here is the CLI example that also shows the default options. You don't need to specify any options unless you wish to override their values.

{
    "plugins": {
        "metalsmith-relative-links": {
            "linkProperty": "link",
            "match": "**/*.{htm,html}",
            "matchOptions": {}
        }
    }
}

// Load this, just like other plugins.
var links = require("metalsmith-relative-links");

// Then in your list of plugins you use it.
.use(links())

// Alternately, you can specify options.  The values shown here are
// the defaults.
.use(links({
    // Name of property that should get the link function
    linkProperty: "link",

    // Pattern of files to match
    match: "**/*.htm,html",

    // Options for matching files.  See metalsmith-plugin-kit.
    matchOptions: {},

    // Function to modify links.  See below.
    modifyLinks: function (uri) {
        return uri.replace(/\.md$/, ".html").replace(/(^|\/|\\)index.html$/, "$1");
    }
})

function (uri) {
    // Remove all extensions
    uri = uri.replace(/\.[^.]*$/, "");

    // Make sure we always link to a folder
    uri = uri + "/";

    return uri;
}

function (uri, fromResolved, toResolved) {
    // uri: A relative link that points at the destination
    // fromResolved: The location of the link originator
    // toResolved: The location of the link destination
    return resultThatYouWant;
}

var relativeLinks = require("metalsmith-relative-links");

// Make your metalsmith instance and add this like other middleware.
metalsmith.use(relativeLinks({
    // configuration goes here
}));

console.log(file.link("/a/b/c", "/d/e"));
// "../../../d/e"

console.log(file.link.resolve("../"))
// "../"

// file is the file object for /a/b/c
console.log(file.link.resolve("/d/e"));
// "../../../d/e"

// file is the file object for /a/b/c
// otherFile is the file object for /d/e
console.log(file.link.resolve(otherFile));
// "../../../d/e"

# Install all of the dependencies
npm install

# Run the tests
npm run test