@metalsmith/layouts

A metalsmith plugin for layouts

This plugin allows you to wrap your files in a template (a layout) and abstract repetitive html. The plugin will pass the contents of your files to the layout as the variable contents, and renders the result with the appropriate templating engine. It uses the file extension of your layout to infer which templating engine to use. So layouts with names ending in .njk will be processed as nunjucks, .hbs as handlebars, etc.

If you want to process templating syntax in your files, instead of wrapping them in a template, you can use @metalsmith/in-place. 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][stackoverflow-url] or our [slack channel][slack-url]. For templating engine specific questions try the aforementioned channels, as well as the documentation for jstransformers and your templating engine of choice.

How does it work

Under the hood this plugin uses jstransformers to render your layouts. Since there are over a 100 jstransformers we don't install them automatically, so you'll need to install the jstransformer for the language you want to use.

For example, to render nunjucks you would install jstransformer-nunjucks, to render handlebars you would install jstransformer-handlebars, etc. The plugin will then automatically detect which jstransformers you've installed. See the jstransformer organisation for all available jstransformers and this dictionary to see which extensions map to which jstransformer.

Installation

NPM:

npm install @metalsmith/layouts

Yarn:

yarn add @metalsmith/layouts

Usage

Options

You can pass options to @metalsmith/layouts with the Javascript API or CLI. The options are:

• default: optional. The default layout to apply to files.
• directory: optional. The directory for the layouts. The default is layouts.
• 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 layouts. The default is {}.
• suppressNoFilesError: optional. By default @metalsmith/layouts will exit with an error if there aren't any files to process. Enabling this option will suppress that error.

default

The default layout to use. Can be overridden with the layout key in each file's YAML frontmatter, by passing either a layout or false. Passing false will skip the file entirely.

If a default layout has been specified, @metalsmith/layouts will apply layouts to all files, so you might want to ignore certain files with a pattern. Don't forget to specify the default template's file extension. The snippet below will apply the default.hbs layout to all files, unless overridden in the frontmatter:

import layouts from '@metalsmith/layouts'

metalsmith.use(
  layouts({
    default: 'default.hbs'
  })
)

directory

You can change the directory where @metalsmith/layouts looks for layouts (default=layouts) by supplying the directory option. In the example below we use templates instead:

import layouts from '@metalsmith/layouts'

metalsmith.use(
  layouts({
    directory: 'templates'
  })
)

The directory path is resolved relative to Metalsmith#directory, not Metalsmith#source. If you prefer having the layouts directory inside the Metalsmith source folder, it is advisable to use Metalsmith#ignore:

import layouts from '@metalsmith/layouts'

metalsmith.ignore('layouts').use(
  layouts({
    directory: 'src/layouts'
  })
)

pattern

For example:

import layouts from '@metalsmith/layouts'

metalsmith(__dirname).use(
  layouts({
    pattern: '**/*.html'
  })
)

...would process all files that have the .html extension. Beware that the extensions might be changed by other plugins in the build chain, preventing the pattern from matching. We use multimatch for the pattern matching.

engineOptions

Use engineOptions to pass options to the jstransformer that's rendering your templates. For example:

import layouts from '@metalsmith/layouts'

metalsmith.use(
  layouts({
    engineOptions: {
      cache: false
    }
  })
)

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

suppressNoFilesError

@metalsmith/layouts 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.

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.

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 layout
  • Have a layout without an extension
  • Are not utf-8
  • Have a layout that needs a jstransformer that hasn't been installed

Debug

To enable debug logs, set the DEBUG environment variable to @metalsmith/layouts:

metalsmith.env('DEBUG', '@metalsmith/layouts*')

Alternatively you can set DEBUG to @metalsmith/* to debug all Metalsmith core plugins.

CLI Usage

To use this plugin with the Metalsmith CLI, add @metalsmith/layouts to the plugins key in your metalsmith.json file:

{
  "plugins": [
    {
      "@metalsmith/layouts": {
        "default": null,
        "directory": "layouts",
        "suppressNoFilesError": false,
        "engineOptions": {}
      }
    }
  ]
}

FAQ

I want to use handlebars partials and or helpers.

Use metalsmith-discover-partials and metalsmith-discover-helpers.

I want to change the extension of my templates.

Use metalsmith-rename.

My templating language requires a filename property to be set.

Use metalsmith-filenames.

Credits

• Ismay Wolff for the current shape of the layouts plugin
• 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

License

MIT