{"_id":"@davekinkead/metalsmith-layouts","_rev":"2-c70a0d9c68822ad096a632af3c9899ac","name":"@davekinkead/metalsmith-layouts","dist-tags":{"latest":"2.1.0"},"versions":{"2.1.0":{"author":"","description":"A metalsmith plugin for layouts.","license":"MIT","main":"lib/index.js","name":"@davekinkead/metalsmith-layouts","repository":{"type":"git","url":"git://github.com/davekinkead/metalsmith-layouts.git"},"version":"2.1.0","scripts":{"precommit":"lint-staged","lint:js":"eslint '**/*.js'","lint:prettier":"prettier --list-different '**/*.js'","test":"jest","test:coverage":"jest --coverage && cat ./coverage/lcov.info | coveralls"},"jest":{"collectCoverageFrom":["lib/*.js"]},"greenkeeper":{"ignore":["eslint","eslint-plugin-import"]},"devDependencies":{"assert-dir-equal":"^1.1.0","coveralls":"^3.0.0","eslint":"^4.8.0","eslint-config-airbnb-base":"^12.0.2","eslint-config-prettier":"^2.9.0","eslint-plugin-import":"^2.7.0","husky":"^0.14.3","jest":"^22.0.4","jstransformer-handlebars":"^1.0.0","lint-staged":"^7.0.0","metalsmith":"^2.3.0","prettier":"^1.9.2","rimraf":"^2.6.2"},"dependencies":{"debug":"^3.1.0","inputformat-to-jstransformer":"^1.2.1","is-utf8":"^0.2.1","jstransformer":"^1.0.0","multimatch":"^2.1.0"},"gitHead":"31c2c22c9e4434698a5b05d809a0f4f1231d77f4","bugs":{"url":"https://github.com/davekinkead/metalsmith-layouts/issues"},"homepage":"https://github.com/davekinkead/metalsmith-layouts#readme","_id":"@davekinkead/metalsmith-layouts@2.1.0","_npmVersion":"5.7.1","_nodeVersion":"8.2.1","_npmUser":{"name":"davekinkead","email":"dave@kinkead.com.au"},"dist":{"integrity":"sha512-Z7HkPsQ6gkvqRsu4EQEv8Jh9Iuvy46tKOJWB9Eg/pwDN5R5jW9GVGTQ4RcgN/8M9cZ64kVQdqdlbIW0w+rlKkQ==","shasum":"9b09b140391ac71ee86e7257188cb01c786942f1","tarball":"https://registry.npmjs.org/@davekinkead/metalsmith-layouts/-/metalsmith-layouts-2.1.0.tgz","fileCount":7,"unpackedSize":28369,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIEAV3j6RIeFDf+Jala/w+HwTECyrRGwaU31DiPd3OeQTAiEAiDfhQ6WHWEXUGOg6RI7e7jsdGT9j3KV9YmxhMuAorEU="}]},"maintainers":[{"name":"davekinkead","email":"dave@kinkead.com.au"}],"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/metalsmith-layouts_2.1.0_1521126976138_0.9728788936680528"},"_hasShrinkwrap":false}},"time":{"created":"2018-03-15T15:16:16.056Z","2.1.0":"2018-03-15T15:16:16.187Z","modified":"2022-04-05T03:05:17.204Z"},"maintainers":[{"name":"davekinkead","email":"dave@kinkead.com.au"}],"description":"A metalsmith plugin for layouts.","homepage":"https://github.com/davekinkead/metalsmith-layouts#readme","repository":{"type":"git","url":"git://github.com/davekinkead/metalsmith-layouts.git"},"bugs":{"url":"https://github.com/davekinkead/metalsmith-layouts/issues"},"license":"MIT","readme":"# metalsmith-layouts\n\n[![npm version][version-badge]][version-url]\n[![build status][build-badge]][build-url]\n[![coverage status][coverage-badge]][coverage-url]\n[![greenkeeper][greenkeeper-badge]][greenkeeper-url]\n[![downloads][downloads-badge]][downloads-url]\n\n> A metalsmith plugin for layouts\n\nThis plugin is a polyfill for rendering templates with templating languages that don't support inheritance. It passes your files to a template of your choice (a `layout`) as the variable `contents` and renders the result with the appropriate engine. It uses the file extension of your layout to infer which templating engine to use. So layouts with names ending in `.njk` will be processed as nunjucks, `.hbs` as handlebars, etc.\n\nThe best way to render templates is with [metalsmith-in-place](https://github.com/ismay/metalsmith-in-place) and a templating language that supports inheritance (like [nunjucks](https://mozilla.github.io/nunjucks/templating.html#template-inheritance) or [pug](https://pugjs.org/language/inheritance.html)). That way you'll have a simpler setup that's less error-prone, with support for recursive templating, chained jstransformers and more. So only use this plugin if you have a good reason for wanting to render templates with a language that doesn't support inheritance (like handlebars).\n\nFor support questions please use [stack overflow][stackoverflow-url] or our [slack channel][slack-url]. For templating engine specific questions try the aforementioned channels, as well as the documentation for [jstransformers](https://github.com/jstransformers) and your templating engine of choice.\n\n## How does it work\n\nUnder the hood this plugin uses [jstransformers](https://github.com/jstransformers/jstransformer) to render your layouts. Since there are over a 100 jstransformers we don't install them automatically, so you'll need to install the jstransformer for the language you want to use.\n\nFor example, to render nunjucks you would install [jstransformer-nunjucks](https://github.com/jstransformers/jstransformer-nunjucks), to render handlebars you would install\n[jstransformer-handlebars](https://github.com/jstransformers/jstransformer-handlebars), etc. The plugin will then automatically detect which jstransformers you've installed. See the [jstransformer organisation](https://github.com/jstransformers) for all available jstransformers and [this dictionary](https://github.com/jstransformers/inputformat-to-jstransformer/blob/master/dictionary.json)\nto see which extensions map to which jstransformer.\n\n## Installation\n\n```bash\n$ npm install metalsmith-layouts\n```\n\n## Options\n\nYou 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:\n\n* [default](#default): optional. The default layout to apply to files.\n* [directory](#directory): optional. The directory for the layouts. The default is `layouts`.\n* [pattern](#pattern): optional. Only files that match this pattern will be processed. Accepts a string or an array of strings. The default is `**`.\n* [engineOptions](#engineoptions): optional. Use this to pass options to the jstransformer that's rendering your layouts. The default is `{}`.\n\n### `default`\n\nThe 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.\n\nIf a `default` layout has been specified, `metalsmith-layouts` will apply layouts to all files, so you might want to ignore certain files with a pattern. Don't forget to specify the default template's file extension. So this `metalsmith.json`:\n\n```json\n{\n  \"plugins\": {\n    \"metalsmith-layouts\": {\n      \"default\": \"default.hbs\"\n    }\n  }\n}\n```\n\nWill apply the `default.hbs` layout to all files, unless overridden in the frontmatter.\n\n### `directory`\n\nThe directory where `metalsmith-layouts` looks for the layouts. By default this is `layouts`. So this `metalsmith.json`:\n\n```json\n{\n  \"plugins\": {\n    \"metalsmith-layouts\": {\n      \"directory\": \"templates\"\n    }\n  }\n}\n```\n\nWill look for layouts in the `templates` directory, instead of in `layouts`.\n\n### `pattern`\n\nOnly files that match this pattern will be processed. So this `metalsmith.json`:\n\n```json\n{\n  \"plugins\": {\n    \"metalsmith-layouts\": {\n      \"pattern\": \"**/*.html\"\n    }\n  }\n}\n```\n\nWould process all files that have the `.html` 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.\n\n### `engine`\n\nUse this to specify which jstransformer should be use regardless of the .ext type.  This allows for example, `mustache` engine with `.html` layouts.\n\n```json\n{\n  \"plugins\": {\n    \"metalsmith-layouts\": {\n      \"engine\": \"mustache\"\n    }\n  }\n}\n```\n\n\n### `engineOptions`\n\nUse this to pass options to the jstransformer that's rendering your templates. So this `metalsmith.json`:\n\n```json\n{\n  \"plugins\": {\n    \"metalsmith-layouts\": {\n      \"engineOptions\": {\n        \"cache\": false\n      }\n    }\n  }\n}\n```\n\nWould pass `{ \"cache\": false }` to the used jstransformer.\n\n## Example\n\n### 1. Install dependencies:\n\n```bash\n$ npm install --save metalsmith metalsmith-layouts\n```\n\nIn this case we'll use handlebars, so we'll install jstransformer-handlebars:\n\n```bash\n$ npm install --save jstransformer-handlebars\n```\n\n### 2. Configure metalsmith\n\nWe'll create a `metalsmith.json` configuration file in the root of the project, a file in `./src` that we want to render in a\nlayout and a handlebars layout for metalsmith-layouts to process in `./layouts`:\n\n`./metalsmith.json`\n\n```json\n{\n  \"source\": \"src\",\n  \"destination\": \"build\",\n  \"plugins\": {\n    \"metalsmith-layouts\": true\n  }\n}\n```\n\n`./src/index.html`\n\n```html\n---\ntitle: The title\nlayout: layout.hbs\n---\n<p>Some text here.</p>\n```\n\n`./layouts/layout.hbs`\n\n```handlebars\n<!DOCTYPE html>\n<html>\n  <head>\n    <title>{{ title }}</title>\n  </head>\n  <body>\n    {{{ contents }}}\n  </body>\n</html>\n```\n\n### 3. Build\n\nTo build just run the metalsmith CLI:\n\n```bash\n$ node_modules/.bin/metalsmith\n```\n\nWhich will output the following file:\n\n`./build/index.html`\n\n```html\n<!DOCTYPE html>\n<html>\n  <head>\n    <title>The title</title>\n  </head>\n  <body>\n    <p>Some text here.</p>\n  </body>\n</html>\n```\n\n## FAQ\n\n> I want to use handlebars partials and or helpers.\n\nUse [metalsmith-discover-partials](https://www.npmjs.com/package/metalsmith-discover-partials) and [metalsmith-discover-helpers](https://www.npmjs.com/package/metalsmith-discover-helpers).\n\n> I want to change the extension of my templates.\n\nUse [metalsmith-rename](https://www.npmjs.com/package/metalsmith-rename).\n\n> My templating language requires a filename property to be set.\n\nUse [metalsmith-filenames](https://www.npmjs.com/package/metalsmith-filenames).\n\n## Errors and debugging\n\nIf you're encountering problems you can use [debug](https://www.npmjs.com/package/debug) to enable verbose logging. To enable `debug` prefix your build command with `DEBUG=metalsmith-layouts`. So if you normally run `metalsmith` to build, use `DEBUG=metalsmith-layouts metalsmith` (on windows the syntax is [slightly different](https://www.npmjs.com/package/debug#windows-note)).\n\n### No files to process\n\nThere are several things that might cause you to get a `no files to process` error:\n\n* Your [pattern](#pattern) does not match any files\n* None of your files pass validation, validation fails for files that:\n  * Have no layout\n  * Have a layout without an extension\n  * Are not utf-8\n  * Have a layout that needs a jstransformer that hasn't been installed\n\n## Credits\n\n* [Ian Storm Taylor](https://github.com/ianstormtaylor) for creating [metalsmith-templates](https://github.com/segmentio/metalsmith-templates), on which this plugin was based\n* [Rob Loach](https://github.com/RobLoach) for creating [metalsmith-jstransformer](https://github.com/RobLoach/metalsmith-jstransformer), which inspired our switch to jstransformers\n\n## License\n\n[MIT](https://ismay.mit-license.org/)\n\n[build-badge]: https://travis-ci.org/ismay/metalsmith-layouts.svg\n[build-url]: https://travis-ci.org/ismay/metalsmith-layouts\n[greenkeeper-badge]: https://badges.greenkeeper.io/ismay/metalsmith-layouts.svg\n[greenkeeper-url]: https://greenkeeper.io\n[coverage-badge]: https://coveralls.io/repos/github/ismay/metalsmith-layouts/badge.svg?branch=master\n[coverage-url]: https://coveralls.io/github/ismay/metalsmith-layouts?branch=master\n[downloads-badge]: https://img.shields.io/npm/dm/metalsmith-layouts.svg\n[downloads-url]: https://www.npmjs.com/package/metalsmith-layouts\n[slack-url]: http://metalsmith-slack.herokuapp.com/\n[stackoverflow-url]: http://stackoverflow.com/questions/tagged/metalsmith\n[version-badge]: https://img.shields.io/npm/v/metalsmith-layouts.svg\n[version-url]: https://www.npmjs.com/package/metalsmith-layouts\n","readmeFilename":"README.md"}