@xiphiaz/metalsmith-layouts NPM

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 the variable contents and renders the result with the templating engine of your choice. You can use any templating engine supported by consolidate.js.

For support questions please use stack overflow or our slack channel. For templating engine specific questions try the aforementioned channels, as well as the documentation for consolidate.js and your templating engine of choice.

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 more elaborate examples see the metalsmith tag on stack overflow.

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)
rename: change the file extension of processed files to .html (optional)
directoryFallback: fallback directory to find layouts when not found in directory (optional)
partialsFallback: fallback directory to find partials when not found in partials (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, 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:

{
  "plugins": {
    "metalsmith-layouts": {
      "engine": "swig",
      "default": "default.html"
    }
  }
}

Will apply the default.html layout to all files, unless overridden in the frontmatter.

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.

Make sure to check consolidate.js and your templating engine's documentation for guidelines on how to use partials.

pattern

Only files that match this pattern will be processed. So this metalsmith.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 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:

{
  "plugins": {
    "metalsmith-layouts": {
      "engine": "handlebars",
      "rename": true
    }
  }
}

directoryFallback

The directory where metalsmith-layouts looks for the layouts when not found in directory. So this metalsmith.json:

{
  "plugins": {
    "metalsmith-layouts": {
      "engine": "handlebars",
      "directory": "layouts",
      "directoryFallback": "fallback"
    }
  }
}

Would first check in layouts directory for the layout, and failing that use the file in fallback directory.

partialsFallback

The directory where metalsmith-layouts looks for the partials when not found in partials. So this metalsmith.json:

{
  "plugins": {
    "metalsmith-layouts": {
      "engine": "handlebars",
      "partials": "partials",
      "partialsFallback": "partials-fallback"
    }
  }
}

Would first check in partials directory for the layout, and failing that use the file in partials-fallback directory.

exposeConsolidate

Not available over the metalsmith.json file. Exposes Consolidate.requires as a function.

// ...
.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 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

async consolidate debug extend fs-readdir-recursive is-utf8 lodash.omit multimatch

@infinitebrahmanuniverse/nolb-_xi @everything-registry/sub-chunk-1029 @ubiquits/toolchain @zalastax/nolb-_xi @zerothstack/toolchain

1.7.0

8 years ago

1.6.5

8 years ago