metalsmith-layouts

metalsmith-layouts

A metalsmith plugin for layouts

This plugin is a polyfill for rendering templates with templating languages that don't support inheritance. It passes your files to a template of your choice (a layout) as the variable contents and renders the result with the appropriate 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.

The best way to render templates is with metalsmith-in-place and a templating language that supports inheritance (like nunjucks or pug). That way you'll have a simpler setup that's less error-prone, with support for recursive templating, chained jstransformers and more. So only use this plugin if you have a good reason for wanting to render templates with a language that doesn't support inheritance (like handlebars).

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.

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 install metalsmith-layouts

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. An error won’t be thrown if no files are present for processing.

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. So this metalsmith.json:

{
  "plugins": {
    "metalsmith-layouts": {
      "default": "default.hbs"
    }
  }
}

Will apply the default.hbs layout to all files, unless overridden in the frontmatter.

directory

The directory where metalsmith-layouts looks for the layouts. By default this is layouts. So this metalsmith.json:

{
  "plugins": {
    "metalsmith-layouts": {
      "directory": "templates"
    }
  }
}

Will look for layouts in the templates directory, instead of in layouts.

pattern

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

{
  "plugins": {
    "metalsmith-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 this to pass options to the jstransformer that's rendering your templates. So this metalsmith.json:

{
  "plugins": {
    "metalsmith-layouts": {
      "engineOptions": {
        "cache": false
      }
    }
  }
}

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

suppressNoFilesError

metalsmith-layouts throws an error in metalsmith 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 if you have debugging turned on, you’ll see a message denoting when no files are present for processing.

Example

1. Install dependencies:

$ npm install --save metalsmith metalsmith-layouts

In this case we'll use handlebars, so we'll install jstransformer-handlebars:

$ npm install --save jstransformer-handlebars

2. Configure metalsmith

We'll create a metalsmith.json configuration file in the root of the project, a file in ./src that we want to render in a layout and a handlebars layout for metalsmith-layouts to process in ./layouts:

./metalsmith.json

{
  "source": "src",
  "destination": "build",
  "plugins": {
    "metalsmith-layouts": true
  }
}

./src/index.html

---
title: The title
layout: layout.hbs
---
<p>Some text here.</p>

./layouts/layout.hbs

<!DOCTYPE html>
<html>
  <head>
    <title>{{ title }}</title>
  </head>
  <body>
    {{{ contents }}}
  </body>
</html>

3. Build

To build just run the metalsmith CLI:

$ node_modules/.bin/metalsmith

Which will output the following file:

./build/index.html

<!DOCTYPE html>
<html>
  <head>
    <title>The title</title>
  </head>
  <body>
    <p>Some text here.</p>
  </body>
</html>

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.

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-layouts. So if you normally run metalsmith to build, use DEBUG=metalsmith-layouts 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 layout
  • Have a layout without an extension
  • Are not utf-8
  • Have a layout that needs 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

License

MIT

Changelog

2.3.0 - November 1, 2018

• add support for async rendering