Nitrogen Pumpkin Mulch


    1.2.0 • Public • Published


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

    npm version Build Status Dependencies Dev Dependencies

    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(),, 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.


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


    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.

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


    npm can do this for you.

    npm install --save metalsmith-relative-links


    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": {}

    And here is how to use JavaScript to include the plugin along with a brief description of each option. The JavaScript version also lets you modify the links using your own function with the modifyLinks configuration option.

    // Load this, just like other plugins.
    var links = require("metalsmith-relative-links");
    // Then in your list of plugins you use it.
    // Alternately, you can specify options.  The values shown here are
    // the defaults.
        // Name of property that should get the link function
        linkProperty: "link",
        // Pattern of files to match
        match: "**/*.htm,html",
        // Options for matching files.  See minimatch.
        matchOptions: {},
        // Function to modify links.  See below.
        modifyLinks: function (uri) {
            return uri.replace(/\.md$/, ".html").replace(/(^|\/|\\)index.html$/, "$1");

    This uses minimatch to match files. The .matchOptions object can be filled with options that the minimatch library uses.

    The modifyLinks() function will, by default, change all *.md links into *.html and remove any index.html at the end of a URI. If you'd like different behavior, this function is able to be replaced. Let's say you wanted no file extensions ever and always create directory-style permalinks. Here's a sample function that does just that.

    function (uri) {
        // Remove all extensions
        uri = uri.replace(/\.[^.]*$/, "");
        // Make sure we always link to a folder
        uri = uri + "/";
        return uri;

    For more complex behavior, the modifyLinks() function is passed additional arguments.

    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;



    metalsmith-relative-links adds functions to the metadata that will generate relative links between different files in the build.


    var relativeLinks = require("metalsmith-relative-links");
    // Make your metalsmith instance and add this like other middleware.
        // configuration goes here

    module.exports(options) ⇒ function

    Factory to build middleware for Metalsmith.

    Kind: Exported function Params

    module.exports~modifyLinks(uri) ⇒ string

    Default function for modifying links

    Kind: inner method of module.exports Params

    • uri string

    module.exports~makeLinkFunction(allFiles, fileName) ⇒ function

    Creates the link function and sets additional properties on the link function in order to easily resolve links or create links with a reference to a specific file object.

    Kind: inner method of module.exports Params

    makeLinkFunction~link(from, to) ⇒ string

    Return a relative URL between two things. This is the function that is generated for each file object provided by Metalsmith.

    Kind: inner method of makeLinkFunction Params


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

    link.from(from) ⇒ string

    Shorthand for calling .link(from, thisFileObject)

    Kind: static method of link Params

    link.resolve(what) ⇒ string

    Resolves a thing into a string. Accepts file objects that are in the list of all source files, strings relative to the current file object's path (../whatever.html), strings relative to the root (/root.html).

    Kind: static method of link Throws:

    • Error when unable to figure out the link



    // "../"


    // file is the file object for /a/b/c
    // "../../../d/e"


    // file is the file object for /a/b/c
    // otherFile is the file object for /d/e
    // "../../../d/e" ⇒ string

    Shorthand for calling .link(thisFileObject, to)

    Kind: static method of link Params

    module.exports~metalsmithFile : Object

    Metalsmith's file object that represents a single file.

    Kind: inner typedef of module.exports Properties

    Name Type
    contents Buffer
    mode string

    module.exports~metalsmithFileCollection : Object.<string, metalsmith-relative-links~metalsmithFile>

    Metalsmith's collection of file objects.

    Kind: inner typedef of module.exports

    module.exports~options : Object

    Options for the middleware factory.

    Kind: inner typedef of module.exports Properties

    Name Type Default Description
    emptyLink string "./" If a link is empty, use this string instead.
    linkProperty string "link" Property name to add to file metadata.
    match string Defaults to match all files.
    matchOptions Object {} Additional options for matching files.
    modifyLinks function Function to modify links. Default changes ".md" to ".html" and removes "index.html".

    module.exports~resolvable : metalsmithFile | string

    Something that can be resolved.

    • string: file path, both relative and root-relative.
    • Object: a file object.

    Kind: inner typedef of module.exports


    This uses Jasmine, Istanbul and ESLint for tests.

    # Install all of the dependencies
    npm install
    # Run the tests
    npm run test

    This plugin is licensed under the MIT License with an additional non-advertising clause. See the full license text for information.




    npm i metalsmith-relative-links

    DownloadsWeekly Downloads






    Last publish


    • fidian