metalsmith-layouts/Readme.md

# metalsmith-layouts

> A metalsmith plugin for layouts

This plugin renders your source files in a layout. You can use any templating engine supported by [consolidate.js](https://github.com/tj/consolidate.js). Pass options to it 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)

## Installation

```bash
$ npm install git://github.com/ismay/metalsmith-layouts.git
```

## Example

Configuration in `metalsmith.json`:

```json
{
  "plugins": {
    "metalsmith-layouts": {
      "engine": "handlebars"
    }
  }
}
```

Source file `src/index.html`:

```html
---
layout: layout.html
title: The title
---
<p>The contents</p>
```

Layout `layouts/layout.html`:

```html
<!doctype html>
<html>
<head>
  <title>{{title}}</title>
</head>
<body>
{{{contents}}}
</body>
</html>
```

Results in `dist/index.html`:

```html
<!doctype html>
<html>
<head>
  <title>The title</title>
</head>
<body>
  <p>The contents</p>
</body>
</html>
```

## Origins

This plugin originated in [metalsmith-templates issue #35](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/ismay/metalsmith-in-place): `metalsmith-templates` with `inPlace: true`
* [metalsmith-layouts](https://github.com/ismay/metalsmith-layouts): `metalsmith-templates` with `inPlace: false`

Both plugins have been optimised for each use case. For `metalsmith-layouts` the differences with [metalsmith-templates](https://github.com/segmentio/metalsmith-templates) are:

* The `inPlace` option has been removed
* Use `layout` instead of `template` in the front-matter to specify a layout
* The default folder for layouts is `layouts` instead of `templates`

For further documentation see the original [metalsmith-templates](https://github.com/segmentio/metalsmith-templates), but keep these differences in mind.

## License

MIT
Update readme, closes #1 2014-11-17 22:19:05 +01:00			`# metalsmith-layouts`
first commit 2014-02-04 21:47:35 -08:00
Update readme 2014-11-22 10:30:05 +01:00			`> A metalsmith plugin for layouts`
first commit 2014-02-04 21:47:35 -08:00
Update readme 2014-11-22 10:30:05 +01:00			`This plugin renders your source files in a layout. You can use any templating engine supported by [consolidate.js](https://github.com/tj/consolidate.js). Pass options to it 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)
first commit 2014-02-04 21:47:35 -08:00
Add installation instructions 2014-11-18 12:49:20 +01:00			`## Installation`

Add example 2014-11-20 16:36:11 +01:00			```bash
Add installation instructions 2014-11-18 12:49:20 +01:00			`$ npm install git://github.com/ismay/metalsmith-layouts.git`
			```

Add example 2014-11-20 16:36:11 +01:00			`## Example`

			Configuration in `metalsmith.json`:

Specify json 2014-11-22 10:32:43 +01:00			```json
Add example 2014-11-20 16:36:11 +01:00			`{`
			`"plugins": {`
			`"metalsmith-layouts": {`
			`"engine": "handlebars"`
			`}`
			`}`
			`}`
			```

			Source file `src/index.html`:

			```html
			`---`
			`layout: layout.html`
			`title: The title`
			`---`
			`<p>The contents</p>`
			```

			Layout `layouts/layout.html`:

			```html
			`<!doctype html>`
			`<html>`
			`<head>`
			`<title>{{title}}</title>`
			`</head>`
			`<body>`
			`{{{contents}}}`
			`</body>`
			`</html>`
			```

			Results in `dist/index.html`:

			```html
			`<!doctype html>`
			`<html>`
			`<head>`
			`<title>The title</title>`
			`</head>`
			`<body>`
			`<p>The contents</p>`
			`</body>`
			`</html>`
			```

Update readme 2014-11-22 10:30:05 +01:00			`## Origins`

			This plugin originated in [metalsmith-templates issue #35](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/ismay/metalsmith-in-place): `metalsmith-templates` with `inPlace: true`
			* [metalsmith-layouts](https://github.com/ismay/metalsmith-layouts): `metalsmith-templates` with `inPlace: false`

			Both plugins have been optimised for each use case. For `metalsmith-layouts` the differences with [metalsmith-templates](https://github.com/segmentio/metalsmith-templates) are:
0.1.0 * add `string` engine convenience 2014-03-05 21:11:21 -08:00
Update readme, closes #1 2014-11-17 22:19:05 +01:00			* The `inPlace` option has been removed
			* Use `layout` instead of `template` in the front-matter to specify a layout
			* The default folder for layouts is `layouts` instead of `templates`
first commit 2014-02-04 21:47:35 -08:00
Update readme, closes #1 2014-11-17 22:19:05 +01:00			`For further documentation see the original [metalsmith-templates](https://github.com/segmentio/metalsmith-templates), but keep these differences in mind.`
first commit 2014-02-04 21:47:35 -08:00
			`## License`

Update readme, closes #1 2014-11-17 22:19:05 +01:00			`MIT`