woodyrew/metalsmith-in-place

A metalsmith plugin for in-place templating

metalsmith-in-place

A metalsmith plugin for in-place templating

This plugin allows you to render templating syntax in your source files. You can use any templating engine supported by consolidate.js. 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 consolidate.js and your templating engine of choice.

Installation

$ npm install metalsmith-in-place

Example

Configuration in metalsmith.json:

{
  "plugins": {
    "metalsmith-in-place": {
      "engine": "handlebars"
    }
  }
}

Source file src/index.html:

---
title: The title
---
<p>{{title}}</p>

Results in build/index.html:

<p>The title</p>

This is a very basic example. For more elaborate examples see the metalsmith tag on stack overflow.

Options

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

• engine: templating engine (required)
• partials: directory for the partials (optional)
• pattern: only files that match this pattern will be processed (optional)
• rename: change the file extension of processed files to .html (optional)

engine

The engine that will render your templating syntax. Metalsmith-in-place uses consolidate.js to render templating syntax, so any engine supported by consolidate.js can be used. Don't forget to install the templating engine separately. So this metalsmith.json:

{
  "plugins": {
    "metalsmith-in-place": {
      "engine": "swig"
    }
  }
}

Will render your templating syntax with swig.

partials

The directory where metalsmith-in-place looks for partials. Each partial is named by removing the file extension from its path (relative to the partials directory), so make sure to avoid duplicates. So this metalsmith.json:

{
  "plugins": {
    "metalsmith-in-place": {
      "engine": "handlebars",
      "partials": "partials"
    }
  }
}

Would mean that a partial at partials/nav.html can be used as {{> nav }}, and partials/nested/footer.html can be used as {{> nested/footer }}. Note that passing anything but a string to the partials option will pass the option on to consolidate. However, the implementation of consolidate for metalsmith-in-place skips consolidate's readPartials method, so paths to partials in the partials object won't be resolved.

Make sure to check consolidate.js and your templating engine's documentation for guidelines on how to use partials.

pattern

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

{
  "plugins": {
    "metalsmith-in-place": {
      "engine": "handlebars",
      "pattern": "*.hbs"
    }
  }
}

Would only process files that have the .hbs extension. This can be very useful if your src directory contains a lot of large files, as metalsmith-in-place will try to process everything by default.

rename

Change the file extension of processed files to .html (optional). This option is set to false by default. So for example this metalsmith.json:

{
  "plugins": {
    "metalsmith-in-place": {
      "engine": "handlebars",
      "rename": true
    }
  }
}

Would rename the extensions of all processed files to .html.

exposeConsolidate

Not available over the metalsmith.json file. Exposes Consolidate.requires as a function.

// ...
.use(inPlace('swig', {
  exposeConsolidate: function(requires) {
    // your code here
  }
}))
// ...

Consolidate

Any unrecognised options will be passed on to consolidate.js. You can use this, for example, to disable caching by passing cache: false. See the consolidate.js documentation for all options supported by consolidate.

Filename property

Some templating engines require a filename property to be set on each file, if you want to include or extend templates. For that, use metalsmith-filenames.

Origins

This plugin is a fork of the now deprecated metalsmith-templates. Splitting up metalsmith-templates into two plugins was suggested by Ian Storm Taylor. The results are:

• metalsmith-in-place: render templating syntax in your source files.
• metalsmith-layouts: apply layouts to your source files.

License

MIT