README.md

metalsmith-scoped

A Metalsmith meta-plugin. Applies another plugin over a subset of files, based on filename glob patterns from multimatch. The wrapped plugin can only see, create, and edit files matching the given patterns.

Trying to access an out-of-scope file (e.g. files['out/of/scope/file']) returns undefined; trying to create or modify an out-of-scope file (e.g. files['out/of/scope/file'] = { ... }) throws an Error.

Caveats

metalsmith-scoped exposes a Proxy files object to the wrapped plugin. Due to Proxy invariants, out-of-scope files might be visible if files is non-extensible or has non-configurable properties.

Interface

function scoped(plugin, patterns, matchOptions)

• plugin: a metalsmith plugin (that is, a function accepting arguments files, metalsmith, callback, expected to mutate files and call callback when done).

• patterns: an array of strings representing filename glob patterns, in the syntax of multimatch.

• matchOptions: an object containing options passed through to multimatch.

For CLI support, scoped can also be called with a one-argument signature:

function scoped([{pluginName: pluginArgs}, patterns, matchOptions])

• pluginName: a String containing the package name (or other requireable name) of a metalsmith plugin.
• pluginArgs: an argument to be passed to the plugin.

Usage Example

Javascript

const scoped = require('metalsmith-scoped');
const markdown = require('@metalsmith/markdown');

Metalsmith(__dirname)
  .source('src')
  .destination('build')
  .use(scoped(
    markdown(),
    ["posts/**/*.md", "index.md", "**/*.html"],
    {dot: true}
  ))
  .build((err) => {
    if (err) throw err;
  });

CLI

Example metalsmith.json:

{
  "source": "src",
  "destination": "build",
  "plugins": [
    {"metalsmith-scoped": [
      {"@metalsmith/markdown": true},
      ["posts/**/*.md", "index.md", "**/*.html"],
      {"dot": true}
    ]}
  ]
}