UNPKG

2.76 kBMarkdownView Raw
1# metalsmith-layouts
2
3[![Build Status](https://travis-ci.org/superwolff/metalsmith-layouts.svg?branch=update-tests)](https://travis-ci.org/superwolff/metalsmith-layouts) [![Dependency Status](https://david-dm.org/superwolff/metalsmith-layouts.svg)](https://david-dm.org/superwolff/metalsmith-layouts) [![devDependency Status](https://david-dm.org/superwolff/metalsmith-layouts/dev-status.svg)](https://david-dm.org/superwolff/metalsmith-layouts#info=devDependencies)
4
5> A metalsmith plugin for layouts
6
7This plugin passes your source files to a template as `contents` and renders it with the templating engine of your choice. 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:
8
9* `engine`: templating engine (required)
10* `default`: default template (optional)
11* `directory`: directory for the layouts, `layouts` by default (optional)
12* `pattern`: only files that match this pattern will be processed (optional)
13
14## Installation
15
16```bash
17$ npm install metalsmith-layouts
18```
19
20## Example
21
22Configuration in `metalsmith.json`:
23
24```json
25{
26 "plugins": {
27 "metalsmith-layouts": {
28 "engine": "handlebars"
29 }
30 }
31}
32```
33
34Source file `src/index.html`:
35
36```html
37---
38layout: layout.html
39title: The title
40---
41<p>The contents</p>
42```
43
44Layout `layouts/layout.html`:
45
46```html
47<!doctype html>
48<html>
49<head>
50 <title>{{title}}</title>
51</head>
52<body>
53{{{contents}}}
54</body>
55</html>
56```
57
58Results in `dist/index.html`:
59
60```html
61<!doctype html>
62<html>
63<head>
64 <title>The title</title>
65</head>
66<body>
67 <p>The contents</p>
68</body>
69</html>
70```
71
72## Origins
73
74This 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:
75
76* [metalsmith-in-place](https://github.com/superwolff/metalsmith-in-place): `metalsmith-templates` with `inPlace: true`
77* [metalsmith-layouts](https://github.com/superwolff/metalsmith-layouts): `metalsmith-templates` with `inPlace: false`
78
79Both plugins have been optimised for each use case. For `metalsmith-layouts` the differences with [metalsmith-templates](https://github.com/segmentio/metalsmith-templates) are:
80
81* The `inPlace` option has been removed
82* Use `layout` instead of `template` in the front-matter to specify a layout
83* The default folder for layouts is `layouts` instead of `templates`
84
85For further documentation see the original [metalsmith-templates](https://github.com/segmentio/metalsmith-templates), but keep these differences in mind.
86
87## License
88
89MIT