metalsmith-mustache-metadata

Metalsmith plugin to modify file metadata to make it easier to work with Mustache templates.

What It Does

This plugin adds a bunch of properties to objects in order to assist you when working with more complex Mustache templates. For instance, sometimes you get a data structure like this:

{
    "module": "something",
    "rootPath": "../../",
    "scripts": [
        "js/first.js",
        "js/second.js"
    ],
    "user": {
        "first": "Tyler"
        "last": "Akins"
    }
}

Your template wants to use the module property and trigger behavior.

{{#module}}
<script src="{{rootPath}}js/super-library.js"></script>
{{/module}}
{{#scripts}}
<script src="{{rootPath}}{{.}}</script>
{{/script}}

Unfortunately, that does not work in Mustache templates because context is switched to the module property and you lose access to all things in the parent. Fret no longer! This plugin adds links throughout the metadata allowing you to determine if a value is set and also to go back to parents. The structure will end up looking somewhat like this:

{
    "module": "something",
    "module?": { *pointer to root object* },
    "rootPath": "../../",
    "rootPath?": { *pointer to root object* },
    "templates": [
        "first",
        "second",
        /* Additional properties added */
        "_parent": { *pointer to root object* }
    ],
    "user": {
        "first": "Tyler",
        "first?": { *pointer to user object* },
        "last": "Akins",
        "last?": { *pointer to user object* },
        "_parent": { *pointer to root object* }
    }
}

This allows you to use the following syntax in your templates. You can also navigate up to parent objects and accomplish all sorts of amazing things in Mustache.

{{#module?}}
<script src="{{rootPath}}js/super-library.js"></script>
{{/module?}}
{{#scripts}}
<script src="{{_parent.rootPath}}{{.}}</script>
{{/script}}

Installation

npm can do this for you.

npm install --save-dev metalsmith-mustache-metadata

Usage

Include this like you would include any other plugin. Here is the CLI example with the default options. You don't need to specify any options unless you want to change their values.

{
    "plugins": {
        "metalsmith-mustache-metadata": {
            "match": "**/*.{htm,html}",
            "matchOptions": {}
        }
    }
}

And here is the JavaScript example. It also includes brief descriptions of each option.

// Load this, just like other plugins.
var mustacheMetadata = require("metalsmith-mustache-metadata");

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

// Alternately, you can specify options.  The values shown here are
// the defaults.
.use(mustacheMetadata({
    // Pattern of files to match
    match: "**/*.{htm,html}",

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

This relies on metalsmith-plugin-kit for matching files. It accepts options to affect the matching rules.

API

metalsmith-mustache-metadata

Metalsmith Mustache Metadata adds references in the metadata and additional properties that make it easier to work with Mustache templates. Typically you can not test for the presence or absense of a value in Mustache templates, which is by design. This allows you to cheat a bit and insert a minor amount of logic in templates, such as "does X exist".

• metalsmith-mustache-metadata
  • module.exports(options) ⇒ function ⏏
    • ~update(thing, parent, forceUpdate)
    • ~metalsmithFile : Object
    • ~metalsmithFileCollection : Object.<string, module:metalsmith-mustache-metadata--module.exports~metalsmithFile>
    • ~options : Object

module.exports(options) ⇒ function ⏏

Factory to build middleware for Metalsmith.

Kind: Exported function Params

• options options

module.exports~update(thing, parent, forceUpdate)

Adds the _parent property to all objects.

Kind: inner method of module.exports Params

• thing Object - Can also include Array objects.
• parent Object | null - null if no parent.
• forceUpdate boolean - Overwrites if _parent already exists

module.exports~metalsmithFile : Object

Metalsmith's file object.

Kind: inner typedef of module.exports Properties

Name	Type
contents	Buffer
mode	string

module.exports~metalsmithFileCollection : Object.<string, module:metalsmith-mustache-metadata--module.exports~metalsmithFile>

Metalsmith's collection of files.

Kind: inner typedef of module.exports

module.exports~options : Object

Options that can be passed to the middleware factory.

Kind: inner typedef of module.exports See: https://github.com/fidian/metalsmith-plugin-kit
Params

• [match] module:metalsmith-plugin-kit~matchList - Defaults to all files
• [matchOptions] module:metalsmith-plugin-kit~matchOptions = {} - Options for matching files.

Development

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.