@metalsmith/layouts

A metalsmith plugin for layouts

[![metalsmith: core plugin][metalsmith-badge]][metalsmith-url]
[![npm: version][npm-badge]][npm-url]
[![ci: build][ci-badge]][ci-url]
[![code coverage][codecov-badge]][codecov-url]
[![license: MIT][license-badge]][license-url]

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:

``bash
npm install @metalsmith/layouts jstransformer-handlebars
`

Yarn:

`bash
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 :

`js
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

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

for a file:

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

with layout:

`hbs


{{title}}

Node v{{nodeVersion}}
`

would render

Article title

Node v16.20.

$3

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, . to force an extension rename.
- engineOptions (Object): optional. Pass options to the jstransformer that's rendering the files. The default is {}.
- pattern (string|string[]): optional. Override default glob pattern matching */.*. 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):

`js
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:

`js
import layouts from '@metalsmith/layouts'

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

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

$3

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 |

$3

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

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

$3

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

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

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

$3

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

`json
{
"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

[npm-badge]: https://img.shields.io/npm/v/@metalsmith/layouts.svg
[npm-url]: https://www.npmjs.com/package/@metalsmith/layouts
[ci-badge]: https://app.travis-ci.com/metalsmith/layouts.svg?branch=master
[ci-url]: https://app.travis-ci.com/github/metalsmith/layouts
[metalsmith-badge]: https://img.shields.io/badge/metalsmith-core_plugin-green.svg?longCache=true
[metalsmith-url]: https://metalsmith.io
[codecov-badge]: https://img.shields.io/coveralls/github/metalsmith/layouts
[codecov-url]: https://coveralls.io/github/metalsmith/layouts
[license-badge]: https://img.shields.io/github/license/metalsmith/layouts
[license-url]: LICENSE