README.md

@metalsmith/metadata

A metalsmith plugin to load global metadata from files and directories.

• Reads, parses and merges data files into global metadata and removes them from the build (when applicable).
• Supports JSON, YAML and TOML files. TOML parser needs to be installed separately.
• Supports dot-notated metadata keypath targets as option keys, eg {'config.nav': 'src/config/nav.yml'}

Installation

NPM:

npm install @metalsmith/metadata

Yarn:

yarn add @metalsmith/metadata

Usage

Pass the options to Metalsmith#use. The options object is in the format { 'metadata.key': 'path/to/(file.ext|dir)' }. Relative file/directory paths are resolved to metalsmith.directory(). Directory option keys will include direct children of the directory, see Mapping nested metadata directories for creating nested directory structures.

import Metalsmith from 'metalsmith'
import metadata from '@metalsmith/metadata'

const __dirname = dirname(new URL(import.meta.url).pathname)

Metalsmith(__dirname)
  .use(
    metadata({
      // in-source JSON file
      jsonFile: 'src/data/a-json-file.json',
      // out-of-source YAML file at nested keypath
      'nested.yamlFile': 'some-directory/a-yaml-file.yaml',
      // out-of-source directory
      aDirectory: 'some-directory/a-directory'
    })
  )
  .build((err) => {
    console.log(metalsmith.metadata())
    // logs { jsonFile: {...}, nested: { yamlFile: {...}}, aDirectory: {...} }
  })

Files inside metalsmith.source() will be considered metadata and thus removed from the build output.

Plugin order

Typically, you want to use this plugin somewhere at the start of the chain, before any rendering plugins run, like @metalsmith/layouts or @metalsmith/in-place.

Merging metadata files into objects

You can merge metadata files into objects by making the root of the data file an object. For example, given the following 2 files:

src/themes/red.json	src/themes/blue.json
{ "red": { "primary-color": "#FF0000" } }	{ "blue": { "primary-color": "#00FF00" } }

with a usage like metalsmith.use(metadata({ themes: 'src/themes' })), metalsmith.metadata().themes will be { red: {"primary-color": #00FF00"}, blue: {"primary-color": "#00FF00"}}.

Merging metadata files into arrays

You can merge metadata files into an array by making the root of the data file an array. For example, given the following 2 files:

src/themes/red.json	src/themes/blue.json
[ { "primary-color": "#FF0000" } ]	[ { "primary-color": "#00FF00" } ]

with a usage like metalsmith.use(metadata({ themes: 'src/themes' })), metalsmith.metadata().themes will be [{"primary-color": #00FF00"}, {"primary-color": "#00FF00"}].

Mapping nested metadata directories

You can map nested metadata directories by specifying multiple options:

metalsmith.use(
  metadata({
    config: 'src/config',
    'config.theme': 'src/config/theme',
    'config.theme.summer': 'src/config/theme/summer',
    'config.constants': 'src/config/constants.yaml'
  })
)

The resulting metadata will have a structure like:

{
  ...otherMetadata,
  config: {
    ...metadata_from_config_dir
    theme: {
      ...metadata_from_config_theme_dir
      summer: { ...metadata_from_config_theme_summer_dir }
    }
  },
  constants: {
    ...metadata_from_config_constants_file
  }
}

Debug

To enable debug logs, set the DEBUG environment variable to @metalsmith/metadata:

metalsmith.env('DEBUG', '@metalsmith/metadata*')

CLI Usage

To use this plugin with the Metalsmith CLI,add the @metalsmith/metadata key to your metalsmith.json plugins. Each key in the dictionary of options will be the key for the global metadata object, like so:

{
  "plugins": {
    "@metalsmith/metadata": {
      "authors": "src/authors.json",
      "categories": "src/categories.yaml",
      "customers": "external_data/customers"
    }
  }
}

License

MIT