@metalsmith/default-values

A Metalsmith plugin for setting default values to file metadata.

Features

sets default values for metadata keys and file contents on files matched by pattern
does not overwrite or transform key values that are already defined
can set computed defaults based on other metadata

Installation

NPM:

npm install @metalsmith/default-values

Yarn:

yarn add @metalsmith/default-values

Usage:

Pass @metalsmith/default-values to metalsmith.use:

import defaultValues from '@metalsmith/default-values'

// single defaults set for all HTML and markdown files
metalsmith.use({
  defaults: {
    pattern: '**/*.md',
    title: 'Lorem ipsum'
  }
})

metalsmith.use(
  defaultValues([
    {
      pattern: 'posts/*.md',
      defaults: {
        layout: 'post.hbs',
        date: function (post) {
          return post.stats.ctime
        }
      }
    },
    {
      pattern: 'diary/*.md',
      defaults: {
        layout: 'diary.hbs',
        private: true
      }
    },
    {
      pattern: ['diary/*.md', 'archive/**/*.md'],
      defaults: {
        no_index: true
      }
    },
    {
      pattern: '**/*.md',
      defaults: {
        layout: 'default.hbs'
      }
    }
  ])
)

Options

@metalsmith/default-values takes an array of defaults sets or a single defaults set. The defaults set has the following properties:

pattern (string|string[]): One or more glob patterns to match file paths. Defaults to '**' (all).
defaults (Object<string, any>): An object whose key-value pairs will be added to file metadata. You can also specify a function callback(file) to set dynamic defaults based on other, existing file metadata.

Examples

Setting default contents

Since version 3.3.0 the Metalsmith File's contents (which are a Node buffer) default can also be set (only if the buffer is empty):

metalsmith.use(
  defaultValues({
    pattern: '**/*.md',
    contents: Buffer.from('TO DO')
  })
)

Combining with other plugins

@metalsmith/default-values works great with other @metalsmith plugins. The example below attaches a collection and layout matching the parent directory for all files in the directories services,products, and articles:

import slugify from 'slugify'
const contentTypes = ['product', 'service', 'article']

metalsmith
  .use(
    defaultValues(
      contentTypes.map((contentType) => ({
        pattern: `${contentType}s/*.md`, // pluralized
        defaults: {
          collection: `${contentType}s`, // pluralized
          bodyClass: contentType,
          layout: `${contentType}.njk`, // using jstransformer-nunjucks
          contentLength(file) {
            if (file.contents) return file.contents.toString().length
            return 0
          }
        }
      }))
    )
  )
  .use(markdown()) // @metalsmith/markdown
  .use(collections()) // @metalsmith/collections
  .use(
    layouts({
      // @metalsmith/layouts
      pattern: '**/*.html'
    })
  )

Debug

To enable debug logs, set the DEBUG environment variable to @metalsmith/default-values*:

metalsmith.env('DEBUG', '@metalsmith/default-values*')

Alternatively you can set DEBUG to @metalsmith/* to debug all Metalsmith core plugins.

CLI usage

To use this plugin with the Metalsmith CLI, add @metalsmith/default-values to the plugins key in your metalsmith.json file:

{
  "plugins": [
    {
      "@metalsmith/default-values": [
        {
          "pattern": "diary/*.md",
          "defaults": {
            "layout": "diary.hbs",
            "private": true
          }
        }
      ]
    }
  ]
}

License

GPL-3.0

npm