*`. Useful to limit the scope of the transform by path or glob to a subfolder, or to include files not matching `transform.inputFormats`.\n\n### Extension handling\n\nBy default in-place will apply smart default extension handling based on `transform.inputFormats` and `transform.outputFormat`.\nFor example, any of the source files below processed through `inPlace({ transform: 'handlebars' })` will yield `index.html`.\n\n| source | output |\n| ------------------ | ---------------- |\n| src/index.hbs | build/index.html |\n| src/index.hbs.html | build/index.html |\n| src/index.html.hbs | build/index.html |\n\nThe example demonstrates that:\n\n- order of extensions doesn't matter, _order of plugin execution does!_: you can pick the final extension to match the most suitable editor syntax highlighting\n- a single in-place run only alters the rightmost extension matching `transform.inputFormats`\n- you may choose to include or omit the `transform.outputFormat` in the source file name (.html in this case).\n\n### `engineOptions`\n\nPass options to the jstransformer that's rendering your templates via `engineOptions`. The\n`metalsmith.json`:\n\n```json\n{\n \"source\": \"src\",\n \"destination\": \"build\",\n \"plugins\": [\n {\n \"@metalsmith/in-place\": {\n \"transform\": \"ejs\",\n \"engineOptions\": {\n \"cache\": false\n }\n }\n }\n ]\n}\n```\n\n..would pass `{ \"cache\": false }` to `jstransformer-ejs`.\n\nIf you use [Pug](https://pugjs.org/api/getting-started.html), make sure to pass `engineOptions: { filename: true }`. This will ensure the filename of each processed file is passed to the render method as expected by this engine.\n\n### Multiple transforms per file\n\nSuppose a file `tags.hbs` that lists all the article tags used on your website\n\n```hbs\n---\ntitle: Tags\ndescription: Browse articles by tag\n---\n{{ title }}
\n{{ description }}
\n\n{{#each tags}}\n - {{ . }}
\n{{/each}}\n
\n```\n\nTo reduce Handlebars noise, you could add `metalsmith.use(inPlace({ transform: 'marked' })` to your build and change the filename to `tags.hbs.md` to generate markdown syntax with Handlebars!\n\n```hbs\n---\ntitle: Tags\ndescription: Browse articles by tag\n---\n\n# {{ title }}\n\n{{ description }}\n\n{{#each tags}}\n- [{{.}}](/tags/{{ . }})\n{{/each}}\n\nMore markdown here..\n```\n\n**Caution**: when using multiple templating transforms per file, make sure there is no conflicting syntax.\nFor example markdown will transform blocks indented by 4 spaces to `` tags, and marked's `smartypants` can potentially garble the result.\n\n### Usage with @metalsmith/layouts\n\nIn most cases `@metalsmith/in-place` is intended to be used _before_ `@metalsmith/layouts`.\nYou can easily share `engineOptions` configs between both plugins:\n\n```js\nimport inPlace from '@metalsmith/in-place'\nimport layouts from '@metalsmith/layouts'\n\nconst engineOptions = {}\nmetalsmith // index.hbs.hbs\n .use(inPlace({ transform: 'handlebars', extname: '', engineOptions })) // -> index.hbs\n .use(layouts({ engineOptions })) // -> index.html\n```\n\n@metalsmith/layouts uses a similar mechanism targeting `transform.inputFormats` file extensions by default.\nThe 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.\n\n### Debug\n\nTo enable debug logs, set the `DEBUG` environment variable to `@metalsmith/in-place*`:\n\n```js\nmetalsmith.env('DEBUG', '@metalsmith/in-place*')\n```\n\nAlternatively you can set `DEBUG` to `@metalsmith/*` to debug all Metalsmith core plugins.\n\n## Credits\n\n- [Ismay Wolff](https://github.com/ismay) for improving upon metalsmith-templates & diligently maintaining its successor\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](LICENSE)\n\n[npm-badge]: https://img.shields.io/npm/v/@metalsmith/in-place.svg\n[npm-url]: https://www.npmjs.com/package/@metalsmith/in-place\n[ci-badge]: https://github.com/metalsmith/in-place/actions/workflows/test.yml/badge.svg\n[ci-url]: https://github.com/metalsmith/in-place/actions/workflows/test.yml\n[metalsmith-badge]: https://img.shields.io/badge/metalsmith-core_plugin-green.svg?longCache=true\n[metalsmith-url]: https://metalsmith.io\n[codecov-badge]: https://img.shields.io/coveralls/github/metalsmith/in-place\n[codecov-url]: https://coveralls.io/github/metalsmith/in-place\n[license-badge]: https://img.shields.io/github/license/metalsmith/in-place\n[license-url]: LICENSE\n","readmeFilename":"README.md"}