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 |
|
7 | This 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 |
|
22 | Configuration in `metalsmith.json`:
|
23 |
|
24 | ```json
|
25 | {
|
26 | "plugins": {
|
27 | "metalsmith-layouts": {
|
28 | "engine": "handlebars"
|
29 | }
|
30 | }
|
31 | }
|
32 | ```
|
33 |
|
34 | Source file `src/index.html`:
|
35 |
|
36 | ```html
|
37 | ---
|
38 | layout: layout.html
|
39 | title: The title
|
40 | ---
|
41 | <p>The contents</p>
|
42 | ```
|
43 |
|
44 | Layout `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 |
|
58 | Results 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 |
|
74 | 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:
|
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 |
|
79 | Both 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 |
|
85 | For further documentation see the original [metalsmith-templates](https://github.com/segmentio/metalsmith-templates), but keep these differences in mind.
|
86 |
|
87 | ## License
|
88 |
|
89 | MIT
|