The contents
``` Layout `layouts/layout.html`: ```htmlThe contents
``` This is a very basic example. For more elaborate examples see the [metalsmith tag on stack overflow][stackoverflow-url]. ## Options You can 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](#engine): templating engine (required) * [default](#default): default template (optional) * [directory](#directory): directory for the layouts, layouts by default (optional) * [partials](#partials): directory for the partials (optional) * [partialExtension](#partialExtension): extension for the partial files (optional) * [pattern](#pattern): only files that match this pattern will be processed (optional) * [rename](#rename): change the file extension of processed files to `.html` (optional) ### engine The engine that will render your layouts. Metalsmith-layouts uses [consolidate.js](https://github.com/tj/consolidate.js) to render templating syntax, so any engine [supported by consolidate.js](https://github.com/tj/consolidate.js#supported-template-engines) can be used. Don't forget to install the templating engine separately. So this `metalsmith.json`: ```json { "plugins": { "metalsmith-layouts": { "engine": "swig" } } } ``` Will render your layouts with swig. ### default The default layout to use. Can be overridden with the `layout` key in each file's YAML frontmatter, by passing either a layout or `false`. Passing `false` will skip the file entirely. If a `default` layout has been specified, `metalsmith-layouts` will process all files unless a pattern has been passed. Don't forget to specify the default template's file extension. So this `metalsmith.json`: ```json { "plugins": { "metalsmith-layouts": { "engine": "swig", "default": "default.html" } } } ``` Will apply the `default.html` layout to all files, unless overridden in the frontmatter. ### directory The directory where `metalsmith-layouts` looks for the layouts. By default this is `layouts`. So this `metalsmith.json`: ```json { "plugins": { "metalsmith-layouts": { "engine": "swig", "directory": "templates" } } } ``` Will look for layouts in the `templates` directory, instead of in `layouts`. ### partials The directory where `metalsmith-layouts` looks for partials. Each partial is named by removing the file extension from its path (relative to the partials directory), so make sure to avoid duplicates. So this `metalsmith.json`: ```json { "plugins": { "metalsmith-layouts": { "engine": "handlebars", "partials": "partials" } } } ``` Would mean that a partial at `partials/nav.html` can be used in layouts as `{{> nav }}`, and `partials/nested/footer.html` can be used as `{{> nested/footer }}`. Note that passing anything but a string to the `partials` option will pass the option on to consolidate. Make sure to check [consolidate.js](https://github.com/tj/consolidate.js) and your templating engine's documentation for guidelines on how to use partials. ### partialExtension The file extension used on partial files. Only the first file matching this file extension will be passed into templating engine. ```json { "plugins": { "metalsmith-layouts": { "engine": "handlebars", "partials": "partials", "partialExtension": ".html" } } } ``` Would mean that even if your partials folder contained `footer.html`, `footer.config.yaml` and `footer.md` (say for documentation or pattern library), only the `footer.html` would be passed to the templating engine. ### pattern Only files that match this pattern will be processed. So this `metalsmith.json`: ```json { "plugins": { "metalsmith-layouts": { "engine": "handlebars", "pattern": "**/*.hbs" } } } ``` Would process all files that have the `.hbs` extension. Beware that the extensions might be changed by other plugins in the build chain, preventing the pattern from matching. We use [multimatch](https://github.com/sindresorhus/multimatch) for the pattern matching. ### rename Change the file extension of processed files to `.html` (optional). This option is set to `false` by default. So for example this `metalsmith.json`: ```json { "plugins": { "metalsmith-layouts": { "engine": "handlebars", "rename": true } } } ``` Would rename the extensions of all processed files to `.html`. ### exposeConsolidate Not available over the `metalsmith.json` file. Exposes Consolidate.requires as a function. ```js // ... .use(layout('swig', { exposeConsolidate: function(requires) { // your code here } })) // ... ``` ### Consolidate Any unrecognised options will be passed on to consolidate.js. You can use this, for example, to disable caching by passing `cache: false`. See the [consolidate.js documentation](https://github.com/tj/consolidate.js) for all options supported by consolidate. ## Origins This plugin is a fork of the now deprecated [metalsmith-templates](https://github.com/segmentio/metalsmith-templates). 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 [build-badge]: https://travis-ci.org/superwolff/metalsmith-layouts.svg [build-url]: https://travis-ci.org/superwolff/metalsmith-layouts [dependency-badge]: https://david-dm.org/superwolff/metalsmith-layouts.svg [dependency-url]: https://david-dm.org/superwolff/metalsmith-layouts [devdependency-badge]: https://david-dm.org/superwolff/metalsmith-layouts/dev-status.svg [devdependency-url]: https://david-dm.org/superwolff/metalsmith-layouts#info=devDependencies [downloads-badge]: https://img.shields.io/npm/dm/metalsmith-layouts.svg [downloads-url]: https://www.npmjs.com/package/metalsmith-layouts [slack-badge]: https://img.shields.io/badge/Slack-Join%20Chat%20→-blue.svg [slack-url]: http://metalsmith-slack.herokuapp.com/ [stackoverflow-badge]: https://img.shields.io/badge/stack%20overflow-%23metalsmith-red.svg [stackoverflow-url]: http://stackoverflow.com/questions/tagged/metalsmith [version-badge]: https://img.shields.io/npm/v/metalsmith-layouts.svg [version-url]: https://www.npmjs.com/package/metalsmith-layouts