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.
$ npm install metalsmith-in-place
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 a ready-to-use boilerplate that utilizes this plugin see metalsmith-boilerplates.
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)
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.
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.
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.
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.
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.
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.
MIT