# metalsmith-layouts
[](https://www.npmjs.com/package/metalsmith-layouts) [](https://travis-ci.org/superwolff/metalsmith-layouts) [](https://david-dm.org/superwolff/metalsmith-layouts) [](https://david-dm.org/superwolff/metalsmith-layouts#info=devDependencies) [](https://www.npmjs.com/package/metalsmith-layouts)
> A metalsmith plugin for layouts
This plugin passes your source files to a template as `contents` and renders them with the templating engine of your choice. You can use any templating engine supported by [consolidate.js](https://github.com/tj/consolidate.js#supported-template-engines). Pass options to `metalsmith-layouts` with the [Javascript API](https://github.com/segmentio/metalsmith#api) or [CLI](https://github.com/segmentio/metalsmith#cli). The options are:
* `engine`: templating engine (required)
* `default`: default template (optional)
* `directory`: directory for the layouts, `layouts` by default (optional)
* `pattern`: only files that match this pattern will be processed (optional)
Any unrecognised options will be passed on to consolidate.js. You can use this, for example, to disable caching by passing `cache: false` to consolidate. See the [consolidate.js documentation](https://github.com/tj/consolidate.js) for all available options.
## Installation
```bash
$ npm install metalsmith-layouts
```
## Example
Configuration in `metalsmith.json`:
```json
{
"plugins": {
"metalsmith-layouts": {
"engine": "handlebars"
}
}
}
```
Source file `src/index.html`:
```html
---
layout: layout.html
title: The title
---
The contents
```
Layout `layouts/layout.html`:
```html
{{title}}
{{{contents}}}
```
Results in `dist/index.html`:
```html
The title
The contents
```
## Origins
This plugin is a fork of [metalsmith-templates](https://github.com/segmentio/metalsmith-templates/issues/35). Splitting up `metalsmith-templates` into two plugins was suggested by Ian Storm Taylor. The results are:
* [metalsmith-in-place](https://github.com/superwolff/metalsmith-in-place): render templating syntax in your source files.
* [metalsmith-layouts](https://github.com/superwolff/metalsmith-layouts): apply layouts to your source files.
## License
MIT