Updates README.md for layouts 3.x

webketje · webketje · commit 89af28b097de · 2025-03-11T00:33:44.000+01:00
diff --git a/README.md b/README.md
@@ -8,102 +8,102 @@ A metalsmith plugin for layouts
 [![code coverage][codecov-badge]][codecov-url]
 [![license: MIT][license-badge]][license-url]
 
-This plugin allows you to wrap your files in a template (a `layout`) and abstract repetitive html. The plugin will pass the contents of your files to the layout as the variable `contents`, and renders the result with the appropriate templating 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.
+## Features
 
-If you want to process templating syntax _in_ your files, instead of wrapping them in a template, you can use [@metalsmith/in-place](https://github.com/metalsmith/in-place). For usage examples check out our [wiki](https://github.com/metalsmith/layouts/wiki). Feel free to contribute an example if anything is missing, or update the existing ones. For 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.
-
-## How does it work
-
-Under 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.
-
-For example, to render nunjucks you would install [jstransformer-nunjucks](https://github.com/jstransformers/jstransformer-nunjucks), to render handlebars you would install
-[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)
-to see which extensions map to which jstransformer.
+- wraps source files' `contents` field in a layout rendered with a [Jstransformer templating engine](https://github.com/jstransformers/jstransformer)
+- alters file extensions from `transform.inputFormats` to `transform.outputFormat`
+- can be used multiple times with different configs per metalsmith pipeline
 
 ## Installation
 
 NPM:
 
 ```bash
-npm install @metalsmith/layouts
+npm install @metalsmith/layouts jstransformer-handlebars
 ```
 
 Yarn:
 
 ```bash
-yarn add @metalsmith/layouts
-```
-
-## Usage
-
-### 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:
+yarn add @metalsmith/layouts jstransformer-handlebars
 
-- [default](#default): optional. The default layout to apply to files.
-- [directory](#directory): optional. The directory for the layouts. The default is `layouts`.
-- [pattern](#pattern): optional. Only files that match this pattern will be processed. Accepts a string or an array of strings. The default is `**`.
-- [engineOptions](#engineoptions): optional. Use this to pass options to the jstransformer that's rendering your layouts. The default is `{}`.
+```
 
-#### `default`
+This plugin works with [jstransformers](https://github.com/jstransformers/jstransformer) but they should be installed separately. `jstransformer-handlebars` is just an example, you could use any transformer. To render markdown you could install [jstransformer-marked](https://github.com/jstransformers/jstransformer-marked). To render handlebars you would install [jstransformer-handlebars](https://github.com/jstransformers/jstransformer-handlebars). Other popular templating options include: [Nunjucks](https://github.com/jstransformers/jstransformer-nunjucks), [Twig](https://github.com/jstransformers/jstransformer-twig), [Pug](https://github.com/jstransformers/jstransformer-pug), or [EJS](https://github.com/jstransformers/jstransformer-ejs). See also [this map](https://github.com/jstransformers/inputformat-to-jstransformer/blob/master/dictionary.json) to see which extensions map to which jstransformer.
 
-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.
+## Usage
 
-If 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. The snippet below will apply the `default.hbs` layout to all files, unless overridden in the frontmatter:
+Pass `@metalsmith/layouts` to `metalsmith.use` :
 
 ```js
 import layouts from '@metalsmith/layouts'
 
+// shorthand
+metalsmith.use(layouts({ transform: 'nunjucks' }))
+
+// same as shorthand
 metalsmith.use(
   layouts({
-    default: 'default.hbs'
+    directory: 'layouts' // === path.join(metalsmith.directory(), 'layouts')
+    transform: jsTransformerNunjucks, // resolved
+    extname: '.html',
+    pattern: '**/*.{njk,nunjucks}*',
+    engineOptions: {}
   })
 )
 ```
 
-#### `directory`
-
-You can change the directory where `@metalsmith/layouts` looks for layouts (default=`layouts`) by supplying the `directory` option. In the example below we use `templates` instead:
+In the transformed file, you have access to `{ ...metalsmith.metadata(), ...fileMetadata }`, so that the following build
 
 ```js
-import layouts from '@metalsmith/layouts'
-
-metalsmith.use(
-  layouts({
-    directory: 'templates'
-  })
-)
+metalsmith
+  .metadata({ title: 'Default title', nodeVersion: process.version })
+  .use(layouts({ transform: 'handlebars' }))
 ```
 
-The directory path is resolved **relative to** `Metalsmith#directory`, not `Metalsmith#source`.
-If you prefer having the layouts directory _inside_ the Metalsmith source folder, it is advisable to use `Metalsmith#ignore`:
+for a file:
 
-```js
-import layouts from '@metalsmith/layouts'
+```yml
+---
+title: Article title
+layout: default.hbs
+---
+```
 
-metalsmith.ignore('layouts').use(
-  layouts({
-    directory: 'src/layouts'
-  })
-)
+with layout:
+
+```hbs
+<h1>{{title}}</h1>Node v{{nodeVersion}}
 ```
 
-#### `pattern`
+would render `<h1>Article title</h1>Node v16.20`.
+
+### Options
+
+In most cases, you will only need to specify the `transform`, `default`, and `engineOptions` option.
 
-For example:
+- transform (`string|JsTransformer`): **required**. Which transformer to use. The full name of the transformer, e.g. `jstransformer-handlebars`, its shorthand `handlebars`, a relative JS module path starting with `.`, e.g. `./my-transformer.js`, whose default export is a jstransformer or an actual jstransformer: an object with `name`, `inputFormats`,`outputFormat`, and at least one of the render methods `render`, `renderAsync`, `compile` or `compileAsync` described in the [jstransformer API docs](https://github.com/jstransformers/jstransformer#api)
+- [extname](#extension-handling) (`string|false|null`): optional. How to transform a file's extensions: `''|false|null` to remove the last `transform.inputFormat` matching extension, `.<ext>` to force an extension rename.
+- [engineOptions](#engineoptions) (`Object<string, any>`): optional. Pass options to the jstransformer that's rendering the files. The default is `{}`.
+- pattern (`string|string[]`): optional. Override default glob pattern matching `**/*.<transform.inputFormats>*`. Useful to limit the scope of the transform by path or glob to a subfolder, or to include files not matching `transform.inputFormats`.
+- default (`string`): optional. The default layout to apply to files matched with `pattern`. If none is given, files matched without defined layout will be skipped. Files whose `layout` is set to `false` will also be skipped.
+- directory (`string`): optional. The directory for the layouts (relative to `metalsmith.directory()`, not `metalsmith.source()`!). Defaults to `layouts`.
+
+#### directory
+
+The directory path is resolved **relative to** `Metalsmith#directory`, not `Metalsmith#source`.
+If you prefer having the layouts directory _inside_ the Metalsmith source folder, it is advisable to use `Metalsmith#ignore` to avoid loading the layouts twice (once via Metalsmith and once via the JSTransformer):
 
 ```js
 import layouts from '@metalsmith/layouts'
 
-metalsmith(__dirname).use(
+metalsmith.ignore('layouts').use(
   layouts({
-    pattern: '**/*.html'
+    directory: 'src/layouts'
   })
 )
 ```
 
-...would 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.
-
 #### `engineOptions`
 
 Use `engineOptions` to pass options to the jstransformer that's rendering your templates. For example:
@@ -122,6 +122,35 @@ metalsmith.use(
 
 Would pass `{ "cache": false }` to the used jstransformer.
 
+### Extension handling
+
+By default layouts will apply smart default extension handling based on `transform.inputFormats` and `transform.outputFormat`.
+For example, any of the source files below processed through `layouts({ transform: 'handlebars' })` will yield `index.html`.
+
+| source             | output           |
+| ------------------ | ---------------- |
+| src/index.hbs      | build/index.html |
+| src/index.hbs.html | build/index.html |
+| src/index.html.hbs | build/index.html |
+
+### Usage with @metalsmith/in-place
+
+In most cases `@metalsmith/layouts` is intended to be used after `@metalsmith/in-place`.
+You can easily share `engineOptions` configs between both plugins:
+
+```js
+import inPlace from '@metalsmith/in-place'
+import layouts from '@metalsmith/layouts'
+
+const engineOptions = {}
+metalsmith // index.hbs.hbs
+  .use(inPlace({ transform: 'handlebars', extname: '', engineOptions })) // -> index.hbs
+  .use(layouts({ transform: 'handlebars', engineOptions })) // -> index.html
+```
+
+@metalsmith/in-place uses a similar mechanism targeting `transform.inputFormats` file extensions by default.
+The example requires files ending in `.hbs.hbs` extension, but if you don't like this, you can just have a single `.hbs` extension, and change the in-place invocation to `inPlace({ engineOptions, transform, extname: '.hbs' })` for the same result.
+
 ### Debug
 
 To enable debug logs, set the `DEBUG` environment variable to `@metalsmith/layouts`:
@@ -150,20 +179,6 @@ To use this plugin with the Metalsmith CLI, add `@metalsmith/layouts` to the `pl
 }
 ```
 
-## FAQ
-
-> I want to use handlebars partials and or helpers.
-
-Use [metalsmith-discover-partials](https://www.npmjs.com/package/metalsmith-discover-partials) and [metalsmith-discover-helpers](https://www.npmjs.com/package/metalsmith-discover-helpers).
-
-> I want to change the extension of my templates.
-
-Use [metalsmith-rename](https://www.npmjs.com/package/metalsmith-rename).
-
-> My templating language requires a filename property to be set.
-
-Use [metalsmith-filenames](https://www.npmjs.com/package/metalsmith-filenames).
-
 ## Credits
 
 - [Ismay Wolff](https://github.com/ismay) for the current shape of the layouts plugin
