metalsmithmetalsmith-in-place
A metalsmith plugin for transforming your source files
This plugin allows you to render templating syntax in your source files. It uses file extensions to infer which templating engine to use. So files ending in .njk will be processed as nunjucks, .md as markdown, etc. You can even chain transformations by appending multiple extensions, which will be processed right-to-left.
If you want to wrap your source files in a common template, you can use metalsmith-layouts. For usage examples check out our wiki. Feel free to contribute an example if anything is missing, or update the existing ones. 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.
Installation
$ npm install metalsmith-in-place
This plugin uses jstransformers to transform files. Since there are a lot of 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.
Options
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. - setFilename: optional. Some templating engines, like pug, need a
filenameproperty to be present in the options to be able to process relative includes, extends, etc. Setting this option totruewill add the current filename to the options passed to each jstransformer. The default isfalse.
pattern
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.
engineOptions
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.
suppressNoFilesError
metalsmith-in-place exits with 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. So this metalsmith.json:
{
"source": "src",
"destination": "build",
"plugins": {
"metalsmith-in-place": {
"suppressNoFilesError": true
}
}
}
Would suppress the error if there aren't any files to process. Note that when this option is turned on, if you're logging debug messages, you’ll still see a message denoting when there aren't any files for metalsmith-layouts to process.
setFilename
Set this option to true if you want to pass the current filename to each jstransformer. The default is false. So this metalsmith.json:
{
"source": "src",
"destination": "build",
"plugins": {
"metalsmith-in-place": {
"setFilename": true
}
}
}
Would overwrite engineOptions.filename with the absolute path for the file that's currently being processed, and pass that to the jstransformer. For now we're just passing filename, but if you encounter a jstransformer that requires a different property, like path or something else, let us know and we can add it.
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
Credits
- Ian Storm Taylor for creating metalsmith-templates, on which this plugin was based
- Rob Loach for creating metalsmith-jstransformer, which inspired our switch to jstransformers