@metalsmith/layouts

A metalsmith plugin for layouts

Features

• wraps source files' contents field in a layout rendered with a Jstransformer templating engine
• alters file extensions from transform.inputFormats to transform.outputFormat
• can be used multiple times with different configs per metalsmith pipeline

Installation

NPM:

npm install @metalsmith/layouts jstransformer-handlebars

Yarn:

yarn add @metalsmith/layouts jstransformer-handlebars

This plugin works with jstransformers but they should be installed separately. jstransformer-handlebars is just an example, you could use any transformer. To render markdown you could install jstransformer-marked. To render handlebars you would install jstransformer-handlebars. Other popular templating options include: Nunjucks, Twig, Pug, or EJS. See also this map to see which extensions map to which jstransformer.

Usage

Pass @metalsmith/layouts to metalsmith.use :

import layouts from '@metalsmith/layouts'

// shorthand
metalsmith.use(layouts({ transform: 'nunjucks' }))

// same as shorthand
metalsmith.use(
  layouts({
    directory: 'layouts' // === path.join(metalsmith.directory(), 'layouts')
    transform: jsTransformerNunjucks, // resolved
    extname: '.html',
    pattern: '**/*.{njk,nunjucks}*',
    engineOptions: {}
  })
)

In the transformed file, you have access to { ...metalsmith.metadata(), ...fileMetadata }, so that the following build

metalsmith
  .metadata({ title: 'Default title', nodeVersion: process.version })
  .use(layouts({ transform: 'handlebars' }))

for a file:

---
title: Article title
layout: default.hbs
---

with layout:

<h1>{{title}}</h1>Node v{{nodeVersion}}

would render <h1>Article title</h1>Node v16.20.

Options

In most cases, you will only need to specify the transform, default, and engineOptions option.

• transform (string|JsTransformer): required. Which transformer to use. The full name of the transformer, e.g. jstransformer-handlebars, its shorthand handlebars, a relative JS module path starting with ., e.g. ./my-transformer.js, whose default export is a jstransformer or an actual jstransformer: an object with name, inputFormats,outputFormat, and at least one of the render methods render, renderAsync, compile or compileAsync described in the jstransformer API docs
• extname (string|false|null): optional. How to transform a file's extensions: ''|false|null to remove the last transform.inputFormat matching extension, .<ext> to force an extension rename.
• engineOptions (Object<string, any>): optional. Pass options to the jstransformer that's rendering the files. The default is {}.
• pattern (string|string[]): optional. Override default glob pattern matching **/*.<transform.inputFormats>*. Useful to limit the scope of the transform by path or glob to a subfolder, or to include files not matching transform.inputFormats.
• default (string): optional. The default layout to apply to files matched with pattern. If none is given, files matched without defined layout will be skipped. Files whose layout is set to false will also be skipped.
• directory (string): optional. The directory for the layouts (relative to metalsmith.directory(), not metalsmith.source()!). Defaults to layouts.

directory

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 to avoid loading the layouts twice (once via Metalsmith and once via the JSTransformer):

import layouts from '@metalsmith/layouts'

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

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.

Extension handling

By default layouts will apply smart default extension handling based on transform.inputFormats and transform.outputFormat. For example, any of the source files below processed through layouts({ transform: 'handlebars' }) will yield index.html.

source	output
src/index.hbs	build/index.html
src/index.hbs.html	build/index.html
src/index.html.hbs	build/index.html

Usage with @metalsmith/in-place

In most cases @metalsmith/layouts is intended to be used after @metalsmith/in-place. You can easily share engineOptions configs between both plugins:

import inPlace from '@metalsmith/in-place'
import layouts from '@metalsmith/layouts'

const engineOptions = {}
metalsmith // index.hbs.hbs
  .use(inPlace({ transform: 'handlebars', extname: '', engineOptions })) // -> index.hbs
  .use(layouts({ transform: 'handlebars', engineOptions })) // -> index.html

@metalsmith/in-place uses a similar mechanism targeting transform.inputFormats file extensions by default. The example requires files ending in .hbs.hbs extension, but if you don't like this, you can just have a single .hbs extension, and change the in-place invocation to inPlace({ engineOptions, transform, extname: '.hbs' }) for the same result.

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",
        "engineOptions": {}
      }
    }
  ]
}

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