Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


4.2.0 • Public • Published


build status coverage status greenkeeper

A metalsmith plugin for rendering templates to html

This plugin allows you to render various templating languages to html. It uses file extensions to infer which templating engine to use. So files ending in .njk will be processed as nunjucks, .pug as pug, etc. You can even chain transformations by appending multiple extensions, which will be processed right-to-left.

For support questions please use stack overflow or our slack channel. For templating engine specific questions try the aforementioned channels, as well as the documentation for jstransformers and your templating engine of choice.


$ npm install metalsmith-in-place


You can pass options to metalsmith-in-place with the Javascript API or CLI. The options are:

  • pattern: optional. Only files that match this pattern will be processed. Accepts a string or an array of strings. The default is **.
  • engineOptions: optional. Use this to pass options to the jstransformer that's rendering your files. The default is {}.
  • suppressNoFilesError: optional. The no-files-to-process error will be suppressed. The default is false.


Only files that match this pattern will be processed. So this metalsmith.json:

  "source": "src",
  "destination": "build",
  "plugins": {
    "metalsmith-in-place": {
      "pattern": "blog/**/*"

Would only process files within the ./src/blog folder, because the pattern is relative to your source folder. See multimatch for further details.


Use this to pass options to the jstransformer that's rendering your templates. So this metalsmith.json:

  "source": "src",
  "destination": "build",
  "plugins": {
    "metalsmith-in-place": {
      "engineOptions": {
        "cache": false

Would pass { "cache": false } to each used jstransformer.


metalsmith-in-place throws an error if it can’t find any files to process. If you’re doing any kind of incremental builds via something like metalsmith-watch, this is problematic as you’re likely only rebuilding files that have changed. This flag allows you to suppress that error (more info).

Note that if you have debugging turned on, you’ll see a message denoting that no files are present for processing.


You can use metalsmith-in-place with metalsmith's Javascript API or the CLI. For this example we'll use the cli:

1. Install metalsmith and metalsmith-in-place:

$ npm install --save metalsmith metalsmith-in-place

2. Install appropriate jstransformers

Under the hood this plugin uses jstransformers to render your html. Since there are over a 100 jstransformers we don't install them automatically, so you'll also need to install the appropriate jstransformers.

For example, to render markdown you would install jstransformer-markdown. To render handlebars you would install jstransformer-handlebars. See the jstransformer organisation for all available jstransformers and this dictionary to see which extensions map to which jstransformer.

In this case we'll use nunjucks, so we'll install jstransformer-nunjucks:

$ npm install --save jstransformer-nunjucks

3. Configure metalsmith

We'll create a metalsmith.json configuration file and a handlebars file for metalsmith-in-place to process:


  "source": "src",
  "destination": "build",
  "plugins": {
    "metalsmith-in-place": true


title: This is a variable, defined in the file's frontmatter
<h1>{{ title }}</h1>
<p>Some text here.</p>

4. Build

To build just run the metalsmith CLI:

$ node_modules/.bin/metalsmith

Which will output the following file:


<h1>This is a variable, defined in the file's frontmatter</h1>
<p>Some text here.</p>

Errors and debugging

If you're encountering problems you can use debug to enable verbose logging. To enable debug prefix your build command with DEBUG=metalsmith-in-place. So if you normally run metalsmith to build, use DEBUG=metalsmith-in-place metalsmith (on windows the syntax is slightly different).

No files to process

There are several things that might cause you to get a no files to process error:

  • Your pattern does not match any files
  • None of your files pass validation, validation fails for files that:
    • Have no extension
    • Are not utf-8
    • Need a jstransformer that hasn't been installed







npm i metalsmith-in-place

Downloadsweekly downloads









last publish


  • avatar
Report a vulnerability