metalsmith-interpolate

metalsmith helper to interpolate strings

• metalsmith-interpolate
  • install
  • usage
  • tokens
    • tokens from path
    • tokens from meta
    • tokens from moment
  • custom tokens
    • simple value tokens
    • calculated value tokens
  • slugify on the fly
  • compatibility
  • Author
  • Contributing
  • License

install

npm i --save metalsmith-interpolate

usage

metalsmith-interpolate is not a plugin, it's a module designed to be used within plugins to provide a consistent interpolation API.

Suppose you made a plugin to generate a coverImage property for each article

import {
  each,
  keys
} from 'lodash'
import metalsmith from 'metalsmith'
import interpolate from 'metalsmith-interpolate'

metalsmith()
...
.use((files, metalsmith, done) => {
  each(multimatch(keys(files), 'articles/**.*'), (src) => {
    files[src].coverImage = interpolate('images/{name}.jpg', src, files)
  })
})
.build()

tokens

tokens from path

properties returned by path.parse:

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
"  /    home/user/dir / file  .txt "
└──────┴──────────────┴──────┴─────┘

• {base} name & ext
• {name}
• {ext} includes the . in .txt
• {dir} path from src directory

tokens from meta

any properties from the metalsmith files structure can be used as tokens

tokens from moment

basically any format tokens from moment including only characters defined by /[MDY\-_\.\/]/. So {YYYY/MMMM} returns 2016/October or whatever.

If a date field is set in a file's frontmatter, then that value will be used, otherwise ctime (file created time) is used instead. Note that moment can only parse dates formatted in limited ways.

custom tokens

simple value tokens

You can add multiple objects to the interpolate arguments to make those properties available as tokens.

metalsmith()
...
.use((files, metalsmith, done) => {
  each(multimatch(keys(files), 'articles/**.*'), (src) => {
    let dimensions = {
      width: 200,
      height: 300
    }
    files[src].coverImage = interpolate(
      'images/{name}_{width}_{height}.jpg',
      src,
      files,
      dimensions
    )
  })
})
.build()

calculated value tokens

You can also add custom a custom resolver function

import { interpolate, resolvers } from 'metalsmith-interpolate'

resolvers.unshift((token, meta) => if (token == 'firstTag') return meta.tags[0])

metalsmith()
...
.use((files, metalsmith, done) => {
  each(multimatch(keys(files), 'articles/**.*'), (src) => {
    files[src].title = interpolate('{title} ({firstTag})', src, files)
  })
})
.build()

The meta argument passed to resolvers contains meta from metalsmith files structure, plus path property, plus any additional properties you passed in.

The first resolver in the array which returns either a truthy value or an 0 length string will be substituted for a given token.

slugify on the fly

prefix a token with - or _ like {-title} to slugify the token's value.

compatibility

dist/index.js is fully compatible with node 6.3.1

dist/node4/index.js is compatible with node 4 LTS, require it like so: var mimeType = require('metalsmith-interpolate/dist/node4')

Author

Levi Wheatcroft [email protected]

Contributing

Contributions welcome; Please submit all pull requests against the master branch.

License

MIT