/metalsmith-inspect

A Metalsmith plugin to debug Metalsmith and plugins. Simpler to use than metalsmith-debug.

Primary LanguageJavaScriptMIT LicenseMIT

Build Status License NPM Downloads Known Vulnerabilities Coverage Status

metalsmith-inspect

A Metalsmith plugin to inspect your file objects. Similar to metalsmith-debug, but:

  • prints the value of contents as a human readable String, not an array of ASCII codes
  • usage is more explicit, with no need to set a DEBUG environment variable. No spooky action at a distance.
  • offers some different options. e.g., control over which fields are included and how to print them.

By default, inspect collects all the file objects into a bigJSObject, then calls console.dir(bigJSObject) (i.e. util.inspect()).

Usage

Install as usual, npm install metalsmith-inspect.

Javascript: use(inspect(options))

CLI: Haven't tested it yet. You'd lose a few options since it can't support functions.

General options

options.filter determines which files will be included

  • if missing, include all files.
  • if a string or Regex, only include matching filePaths.
  • if a user-provided-function, include the file when filter(filePath, data, metalsmith) returns true.
    e.g. If you want to use multimatch, pass something like function(filePath) { return multimatch([filePath], ["blogs/**", ...])[0] };

options.includeMetalsmith if present, include metalsmith metadata under the "file" of that name. e.g. if options.includeMetalsmith = "msmetadata" it will appear in the bigJSObject under the "msmetadata" key.

options.printfn determines what will be done with bigJSObject. Default is console.dir(bigJSObject, {colors: true}); But, if you want to save it to a database or email it to your Russian hacker friends, you can change that here.

options.disable a quick way to turn inspect off (like unsetting the DEBUG environment variable)

options.contentsAsBuffer if true, keep .contents as a Buffer, for those who like to read ASCII codes.

Options controlling which fields are included

Normally, all fields are included. There are several mutually exclusive ways to limit which fields will be included:

options.include: [key1, key2, ...] only include fields in the array.

options.exclude: [key1, key2, ...] include all fields except those in the array. (I like to exclude "stats", and sometimes "next" and "prev" if using collections.)

options.accept: function(keyname, filedata) include field if the user-provided function returns truthy.

Notes, Todos, and Caveats

I wrote this because I was having trouble getting metalsmith-debug to work, and because I saw some possible improvements. Hoping this is useful to the metalsmith community.