in-place
in-place copied to clipboard
Common use case enhancements
First some observations:
- When in-place doesn't find the first transformer for a file (matching the rightmost extension), it leaves it untouched.
- Repeating the same extension multiple times will lead to reprocessing = bugs (eg
index.njk.njk.md.njk.md
) - It is impossible to pass a custom transformer because the logic is handled behind-the-scenes by a hardcoded list of "input-to-jstransformer". As a first step local transformers could be linked in package.json as
"jstransformer-local": "file:jstransformer-local"
- When more than one transformer is used, engineOptions are a mixed config passed to all transformers, this is less than ideal.
-
extension chaining: Although technically in-place would process a file
index.ejs.md.njk.twig.hbs
if all transformers are installed, nobody in their right mind would mix 5 templating languages with conflicting syntaxes. -
markdown convenience: When using
@metalsmith/markdown
orjstransformer-marked
with in-place, the desirable extension order is always*.md
at the end to enable markdown syntax highlighting in code editors. But running markdown before other transformers is highly likely to garble the intermixed syntax. An alternative to combining markdown is registering a custom markdown helper in the template language of choice -
in-place/ layouts interop: There are 2 ways to use both layouts & in-place functionality: the first is to use the 2 plugins (in-place first, then layouts).
The second is to use in-place only and use templating constructs inside content files with "slots", eg for nunjucks:
{% extends 'layout.njk' %}
. The first is convenient because layouts can be applied through file frontmatter (or assigned with plugins). The second needs to "wrap" the content in each file. However, both plugins rename the extensions to html, which forces the second one to use a target pattern ending in.html
.
Some potential solutions:
- Alternative matching algo with noop for unmatched extensions
- Filter extensions by unique starting from the right
- remove inputformat-to-jstransformer dependency or use as fallback, allow explicitly passing jstransformers through a new option
- split engineOptions in subkeys, eg
engineOptions: { marked: {...}, nunjucks: {...}
- None
- When detecting .md, always move it to the last position to be processed (leaky)
- Provide an extRename option:
false|true|<ext>