Skip to content
Metalsmith plugin to iterate through the properties of an object provided as frontmatter. For each property it renders the value using a jstransformer.
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 render strings within frontmatter.

You could have used metalsmith-frontmatter-file-loader to get those strings from seperate files.

Build Status


$ npm install metalsmith-frontmatter-renderer

Note: you will need to install the jstranformer that you want to use. No transformers are required as dependencies of this package.

e.g. to use the default markdown transformer you will need to also run $ npm install jstransformer-markdown

Config options

You can pass some basic options to customize the behaviour:

  "key": "blocks",
  "out": "blocks",
  "ext": "md",
  "suppressNoFilesError": false,
  "options": {}
  • key is the key of the object to iterate over in the files frontmatter. Default blocks.
  • out is the key of the object to update the values upon. Default the value of key.
  • ext is a string used by inputformat-to-jstransformer to determine which jstransformer to load and use. Note: you do need to install whichever jstransformer you want to use. Default md.
  • suppressNoFilesError is a boolean to determine the behaviour when there are no files to look check the frontmatter of. Set to true to prevent an error being thrown if there are no files. Default false.
  • options is an object that will be passed to the jstransformer render function as the second parameter (options). Default to empty object {}.

CLI Usage

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

  "plugins": {
    "metalsmith-frontmatter-renderer": true

or with configuration options:

  "plugins": {
    "metalsmith-frontmatter-renderer": {
      "key": "files",
      "out": "blocks-rendered",
      "ext": "njk",
      "suppressNoFilesError": true,
      "options": {
        "html": true

Javascript Usage

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

var fmfl = require('metalsmith-frontmatter-renderer');

  key: 'files',
  ext: 'njk',
  suppressNoFilesError: true

Example frontmatter


    foo: '# Here is some *markdown*'
    bar: '`blocks` will be rendered using a [jstranformer]('
<h1>This is the <code>contents</code> of the file.</h1>

By default this would render the two properties foo and bar using the markdown jstransformer. It would replace the contents of those two properties with the rendered string.

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

    foo: '<h1>Here is some <em>markdown</em></h1>'
    bar: '<p><code>blocks</code> will be rendered using a <a href="">jstranformer</a></p>'
<h1>This is the <code>contents</code> of the file.</h1>

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



You can’t perform that action at this time.