Skip to content
Metalsmith plugin to iterate through the properties of an object provided as frontmatter. For each property it replaces the value with the string contents of a utf-8 encoded file resolved using the original value as a file path.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


A Metalsmith plugin to load files from paths added to frontmatter.

You could then use metalsmith-frontmatter-renderer to render the loaded data into html.

Build Status


$ npm install metalsmith-frontmatter-file-loader

Config options

You can pass some basic options to customize the behaviour:

  "key": "files",
  "out": "files",
  "suppressNoFilesError": false,
  "allowMissingFiles": false
  • key is the key of the object to iterate over in the files frontmatter. Default "files".
  • out is the key of the object to update the values upon. Default the value of key.
  • suppressNoFilesError is a boolean to determine the behaviour when there are no files to load. Set to true to prevent an error being thrown if there are no files to load. Default false.
  • allowMissingFiles is a boolean to determine the behaviour when a file fails to load. Set to true to prevent an error being thrown if a file is missing or cannot be read as a utf-8 string. If a file fails to load then it will replace the value with an empty string. Default false.

CLI Usage

Install via npm and then add the metalsmith-frontmatter-file-loader key to your metalsmith.json plugin:

  "plugins": {
    "metalsmith-frontmatter-file-loader": true

or with configuration options:

  "plugins": {
    "metalsmith-frontmatter-file-loader": {
      "key": "blocks",
      "suppressNoFilesError": true,
      "allowMissingFiles": true

Javascript Usage

Pass options to the plugin and pass it to Metalsmith with the use method:

var fmfl = require('metalsmith-frontmatter-file-loader');

  key: "blocks",
  suppressNoFilesError: true,
  allowMissingFiles: true

Example frontmatter


    foo: './files/foo.txt'
    bar: './files/'
<h1>This is the <code>contents</code> of the file.</h1>

By default this would load the contents of ./files/foo.txt (relative to the metalsmith root, not the file containing the frontmatter) and replace the path with the file contents. Then it would do the same for ./files/ It doesn't do any conversion of the data but you can use metalsmith-frontmatter-renderer if you desire this behaviour.

e.g this is the equivalent of having written out the file contents into the frontmatter as so:

    foo: 'This is the text content of ./files/foo.txt!'
    bar: 'This is the *markdown* content of `./files/` :)'
<h1>This is the <code>contents</code> of the file.</h1>

If you use a property other than files then you can pass the name as a configuration option. See the config documentation above.



You can’t perform that action at this time.