Skip to content
πŸ“” A Metalsmith plugin to add a directory of JSON files for use as global metadata in templates, partials and pages.
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.


npm Build Status GitHub license

A Metalsmith plugin to add a directory of JSON and/or YAML files for use as global metadata in templates, partials and pages.


This plugin supports adding a directory of .json & .yml/.yaml files and makes their contents available to the Metalsmith global metadata, without needing to declare multiple file names. Subdirectories and multiple files are supported by using a globbing pattern.

Node support

This plugin is supported and tested against all the current Node LTS versions (10 & 12). This plugin should work on Node 6 & 8 but is not supported for these versions.


Install the plugin using npm, and specify the directory of metadata files you want to use, along with a globbing pattern.

$ npm install metalsmith-metadata-directory --save-dev

With Metalsmith CLI

Add the plugin to your metalsmith.json file:

  "plugins": {
    "metalsmith-metadata-directory": {
      "directory": "/src/data/**/*.json"

NOTE: .yml and .yaml file extensions are also supported.

With JavaScript

Pass the plugin into metalsmith.use:

var metalsmith = require('metalsmith')
var metadata = require('metalsmith-metadata-directory')

  directory: '/src/data/**/*.json',
  // or for YAML respectively; be sure to use 'yml' or 'yaml' as file suffix
  directory: '/src/data/**/*.yml'

Plugin ordering

It is vital to order Metalsmith plugins correctly. Please make sure this plugin is included above metalsmith-layouts and metalsmith-in-place and any other plugin which may use your metadata.

Usage within Metalsmith

Data is called by referencing the filename without an extension. For example, if there was a global.json file containing a url key, the reference in your page or template would look like:


Debug mode

This plugin supports debugging output. To enable, use the following command when running Metalsmith:

$ DEBUG=metalsmith-metadata-directory metalsmith



You can’t perform that action at this time.