metalsmith-link-globs

v1.1.0

Published

4 years ago

Metalsmith plugin to repeat elements that use globs to match multiple files.

0High
0Medium
0Low

Metalsmith Link Globs

Repeat your <script>, <link>, <img> and <a> tags in your HTML by using a wildcard pattern in your src= or href= attributes.

Overview

When building HTML files that should link to a bunch of JavaScript files, one can hardcode each link, but that is tedious. It also doesn't work well when you want to use the same HTML but link to JavaScript that has not been concatenated nor minified. Why not just pull the list of files from Metalsmith?

<html>
    <head>
        <title> BEFORE THE PLUGIN </title>
        <script src="third-party/angular.js"></script>
        <script src="third-party/angular-ui.js"></script>
        <script src="third-party/sha512.js"></script>
        <script src="my-app.js"></script>
        <script src="other-thing.js"></script>
        <link rel="stylesheet" href="third-party/normalize.css">
        <link rel="stylesheet" href="third-party/angular-ui.css">
        <link rel="stylesheet" href="themes/clean-looks.css">
        <link rel="stylesheet" href="themes/base.css">
        <link rel="stylesheet" href="site.css">
        <link rel="stylesheet" href="atomic.css">

This can be reduced to the following:

<html>
    <head>
        <title> WITH THE PLUGIN </title>
        <script src="third-party/**/*.js"></script>
        <script src="!(third-party)**/*.js"></script>
        <link rel="stylesheet" href="**/*.css">

You would simply add this plugin to your .use() chain in Metalsmith.

var linkGlobs = require("metalsmith-link-globs");

// ...
.use(linkGlobs);

If the default settings don't work for you, there are options you can use to tailor how the library works.

Installation

Use npm to install this package easily.

$ npm install --save metalsmith-link-globs

Alternately you may edit your package.json and add this to your dependencies object:

{
    ...
    "dependencies": {
        ...
        "metalsmith-link-globs": "*"
        ...
    }
    ...
}

Usage

Include this plugin the same as any other Metalsmith plugin. This first example shows how you would add it using a JSON configuration. It also shows the default settings. These are described later.

{
    "plugins": {
        "metalsmith-link-globs": {
            "elementMatchOptions": {},
            "encoding": "utf8",
            "match": "**/*.html",
            "matchOptions": {},
            "nodes": [
                {
                    "element": "a",
                    "property": "href"
                },
                {
                    "element": "img",
                    "property": "src"
                },
                {
                    "element": "link",
                    "property": "href"
                },
                {
                    "element": "script",
                    "property": "src"
                }
            ]
        }
    }
}

This is a JavaScript example, which also includes a brief explanation of the options.

var linkGlobs = require("metalsmith-link-globs");

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

// Alternately, you can specify options. The values shown here are
// the defaults.
.use(linkGlobs({
    // Matching options for the glob patterns that are used within
    // elements.
    "elementMatchOptions": {},

    // How buffers are decoded into text and encoded again. Only
    // affects the files being changed.
    "encoding": "utf8",

    // What files to target.
    "match": "**/*.html",

    // Options to select what files should be targeted.
    "matchOptions": {},

    // A list of HTML element and property names that should be
    // processed.
    "nodes": [
        {
            "element": "a",
            "property": "href"
        },
        {
            "element": "img",
            "property": "src"
        },
        {
            "element": "link",
            "property": "href"
        },
        {
            "element": "script",
            "property": "src"
        }
    ]
});

This uses metalsmith-plugin-kit to match files. The .matchOptions and .elementMatchOptions objects are just options passed directly to that library for matching files.

If you want to see what files are processed, what elements are found and the resulting list of matching files, enable debugging.

DEBUG=metalsmith-link-globs metalsmith

API

metalsmith-link-globs

Metalsmith Link Globs will repeat HTML elements so you can link to one or several files, based on what is in your build. Your debug build may not combine and minify files but your production build does. Eliminate the hassle and use a layout like this to link all files.

<script src="js/*.js"></script>

metalsmith-link-globs
- module.exports(options) ⇒ function ⏏
  - ~processNode(node, sourceFile, content, fileList)
  - ~metalsmithFile
  - ~metalsmithFileCollection : Object.<string, module:metalsmith-link-globs--module.exports~metalsmithFile>
  - ~nodeDefinition : Object
  - ~options : Object

module.exports(options) ⇒ function ⏏

Factory to build middleware for Metalsmith.

Kind: Exported function Params

options options

module.exports~processNode(node, sourceFile, content, fileList)

Rewrites element tags in the HTML for a given node definition.

Kind: inner method of module.exports Params

node Object
sourceFile string
content Cheerio
fileList Array.<string>

module.exports~metalsmithFile

Metalsmith file object.

Kind: inner typedef of module.exports Properties

| Name | Type | | --- | --- | | contents | Buffer | | mode | string |

module.exports~metalsmithFileCollection : Object.<string, module:metalsmith-link-globs--module.exports~metalsmithFile>

Metalsmith collection of files.

Kind: inner typedef of module.exports

module.exports~nodeDefinition : Object

Defines a node name and the property that has the glob expression. For instance, images may look like <img src="*.jpg">. This would match all jpeg files in the current folder. The definition for img tags should look like this:

{
    element: "img",
    property: "src"
}

Kind: inner typedef of module.exports Properties

| Name | Type | Description | | --- | --- | --- | | element | string | Name of element to fine. | | property | string | Attribute or property name of the element that contains the glob expression. |

module.exports~options : Object

Options for the middleware factory.

Kind: inner typedef of module.exports Properties

| Name | Type | Default | Description | | --- | --- | --- | --- | | elementMatchOptions | module:metalsmith-plugin-kit~matchOptions | {} | Controls what files match the patterns found in the HTML elements. | | encoding | string | "utf8" | Buffer encoding. | | match | module:metalsmith-plugin-kit~matchList | | Defaults to *.html in any folder. | | matchOptions | module:metalsmith-plugin-kit~matchOptions | {} | Controls how to find files that have elements to repeat. | | nodes | Array.<module:metalsmith-plugin-kit~nodeDefinition> | | What HTML elements to process. Defaults to a, img, link and script. |

Development

This uses Jasmine, Istanbul and ESLint for tests.

# Install all of the dependencies
npm install

# Run the tests
npm run test

License

This software is licensed under a MIT license that contains additional non-advertising and patent-related clauses. Read full license terms

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Metalsmith Link Globs

Overview

Installation

Usage

API

metalsmith-link-globs

module.exports(options) ⇒ function ⏏

module.exports~processNode(node, sourceFile, content, fileList)

module.exports~metalsmithFile

module.exports~metalsmithFileCollection : Object.<string, module:metalsmith-link-globs--module.exports~metalsmithFile>

module.exports~nodeDefinition : Object

module.exports~options : Object

Development

License