🏙️ A metalsmith plugin for in-place templating
Clone or download

README.md

metalsmith-in-place

build status coverage status greenkeeper

A metalsmith plugin for transforming your source files

This plugin allows you to transform the contents of your source files. It uses file extensions to infer which transform 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.

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.

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 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.

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

License

MIT