| .. | ||
| lib | ||
| node_modules | ||
| test | ||
| .editorconfig | ||
| .eslintrc | ||
| .gitattributes | ||
| .npmignore | ||
| .travis.yml | ||
| History.md | ||
| Makefile | ||
| package.json | ||
| Readme.md | ||
metalsmith-layouts
A metalsmith plugin for layouts
This plugin allows you to apply layouts to your source files. It passes your source files to the selected layout as contents and renders the result with the templating engine of your choice. You can use any templating engine supported by consolidate.js.
Installation
$ npm install metalsmith-layouts
Example
Configuration in metalsmith.json:
{
"plugins": {
"metalsmith-layouts": {
"engine": "handlebars"
}
}
}
Source file src/index.html:
---
layout: layout.html
title: The title
---
<p>The contents</p>
Layout layouts/layout.html:
<!doctype html>
<html>
<head>
<title>{{title}}</title>
</head>
<body>
{{{contents}}}
</body>
</html>
Results in build/index.html:
<!doctype html>
<html>
<head>
<title>The title</title>
</head>
<body>
<p>The contents</p>
</body>
</html>
This is a very basic example. For a ready-to-use boilerplate that utilizes this plugin see metalsmith-boilerplates.
Options
You can pass options to metalsmith-layouts with the Javascript API or CLI. The options are:
- engine: templating engine (required)
- default: default template (optional)
- directory: directory for the layouts, layouts by default (optional)
- partials: directory for the partials (optional)
- pattern: only files that match this pattern will be processed (optional)
engine
The engine that will render your layouts. Metalsmith-layouts uses consolidate.js to render templating syntax, so any engine supported by consolidate.js can be used. Don't forget to install the templating engine separately. So this metalsmith.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. If a default layout hasn't been specified, metalsmith-layouts will only process files with a layout option in their front-matter. Don't forget to specify the file extension. So this metalsmith.json:
{
"plugins": {
"metalsmith-layouts": {
"engine": "swig",
"default": "default.html"
}
}
}
Will apply the default.html layout to all files, unless specified otherwise in the frontmatter.
directory
The directory where metalsmith-layouts looks for the layouts. By default this is layouts. So this metalsmith.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:
{
"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.
pattern
Only files that match this pattern will be processed. So this metalsmith.json:
{
"plugins": {
"metalsmith-layouts": {
"engine": "swig",
"pattern": "*.md"
}
}
}
Would only process files that have the .md extension.
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 for all options supported by consolidate.
Origins
This plugin is a fork of the now deprecated metalsmith-templates. Splitting up metalsmith-templates into two plugins was suggested by Ian Storm Taylor. The results are:
- metalsmith-in-place: render templating syntax in your source files.
- metalsmith-layouts: apply layouts to your source files.
License
MIT