API.md

Table of Contents

• metalsmithIncremental
• filter
• cache
• watch
• PathsObject
• DependencyResolver
• IncrementalDoneFn
• RenameFunction
• DependencyResolverMap
• RenameObject
• PathObject
• PropsList

metalsmithIncremental

Returns the selected metalsmith-incremental sub plugin. Use:

• filter: to remove unmodified files from the pipeline
• cache: to cache current state in the pipeline and to restore filtered files by filter
• watch: to start watching for file changes (can be used only once)

Parameters

• options Object? Plugin options hash.
  • options.plugin string? Specify the sub plugin to use - filter, cache or watch. (optional, default filter)
  • options.baseDir string? The baseDir to which to resolve absolute paths in dependencies (filter only).
  • options.depResolver (RegExp | DependencyResolver | DependencyResolverMap)? A RegExp pattern or callback to resolve dependencies (filter only).
  • options.rename (RenameObject | RenameFunction)? A function or object defining renaming rules (cache only).
  • options.props PropsList? An array of property names to sync from cached files to new files (cache only). (optional, default ['contents'])
  • options.paths (PathsObject | string)? A glob-pattern map which forces updates of mapped files (watch only).
  • options.delay number? The number of milliseconds the rebuild is delayed to wait for additional changes (watch only). (optional, default 100)
  • options.done IncrementalDoneFn? A callback to call after incremental build has finished (same signature as fn in metalsmith.build(fn) (watch only).

Returns (filter | cache | watch) Returns the specified metalsmith sub plugin - filter, cache or watch.

filter

Removes unmodified files from the pipeline by resolving:

• changed, added, removed files or directories
• resolving glob map matches
• infer dependencies

Options

• baseDir
• depResolver

Parameters

• files Object
• metalsmith MetalSmith
• done Function

Examples

metalsmith.usw(incremental({
 plugin: 'filter', // default 'filter' -> can be omitted
 baseDir: 'your/base/dir',
}))

Resolving Dependencies by RegExp

metalsmith.usw(incremental({
 baseDir: 'your/base/dir',
 // important the first capturing group must contain the dependency path
 depResolver: /(?:include|extends)\s+([^\s]+)/mg,
}))

Resolving Dependencies by Hash-Map

metalsmith.usw(incremental({
 baseDir: 'your/base/dir',
 depResolver: {
   pug: /(?:include|extends)\s+([^\s]+)/mg,
 },
}))

Resolving Dependencies by Function

metalsmith.usw(incremental({
 baseDir: 'your/base/dir',
 depResolver: (file, baseDir) {
   // read file contents
   const contents = file.contents
   const dependencies = []

   // ... your custom dependencies resolve algorith here

   return dependencies
 },
}))

cache

Caches all files at the specific point in the pipeline and restores unmodified files filtered previously by filter.

Options

• rename
• props

Parameters

• files Object
• metalsmith MetalSmith
• done Function

Examples

metalsmith.use(increment({
 plugin: 'cache',
})

Renaming files by RegExp

metalsmith.use(increment({
 plugin: 'cache',
 rename: {
   from: /.pug$/,
   to: '.html',
 },
})

Renaming files by function

metalsmith.use(increment({
 plugin: 'cache',
 rename: (path) => {
   path.extname = path.extname.replace('.pug', '.html')

   return path
 },
})

watch

Starts watching for file system changes inside metalsmith.source() directory.

Options

• paths
• delay
• done

Parameters

• files Object
• metalsmith MetalSmith
• done Function

Examples

// optionally enable watching
if(process.env.NODE_ENV === 'development') {
 metalsmith.use(incremental({ plugin: 'watch' }))
}

Set debounce delay in [ms]

metalsmith.use(incremental({
 plugin: 'watch',
 debounce: 200,
}))

Force to rebuild other unmodified files by glob pattern map

metalsmith.use(incremental({
 plugin: 'watch',
 paths: {
   'foo/*.md': 'bar/*.pug',
 },
}))

PathsObject

Paths pattern map to force rebuilding unmodified files.

{
  'file(s) to watch': 'file(s) to rebuild'
}

{
  'templates/*': '*', // every templates changed will trigger a rebuild of all files
}

Type: Object

DependencyResolver

A callback which defines renaming rules.

Type: Function

Parameters

• file Object The currently processed file.
• baseDir string The supplied baseDir by options.baseDir.

Returns (Array | null) dependencies - Returns an array of dependencies (relative to baseDir).

IncrementalDoneFn

A callback to call after incremental build has finished (same signature as fn in metalsmith.build(fn).

Type: Function

Parameters

• error (null | any) Set only if an error has occurred.
• files Object A hash of files build by Metalsmith.

RenameFunction

A callback which defines renaming rules.

Type: Function

Parameters

• path PathObject The current path of the file.

Returns PathObject path - The new path to be used.

DependencyResolverMap

An object mapping file extension to related dependency resolving methods.

Important The first capturing group of your RegExp needs to contain the dependency path.

Type: Object<string, (RegExp | DependencyResolver)>

RenameObject

An object which defines renaming rules.

Type: Object

Properties

• from (RegExp | string) A pattern to match.
• to string A string to replace matched value.

PathObject

An object which defines a path.

Type: Object

Properties

• path.basename string The name of the file without it's extension.
• path.dirname string The directory path of the file.
• path.extname string The file extension (including the dot).

PropsList

A single property or list of properties to sync between cached and new files, representing either one single property or a complete property path, like:

var obj = {
 foo: 1,
 bar: 2,
 snafu: {
   foo: 3,
   baz: 4
 }
}

'foo'  // single property -> obj.foo
['foo', 'bar']   // property list -> obj.foo, obj.bar
[['snafu', 'foo']]   // property path -> obj.snafu.foo

Type: (string | Array<(string | Array<string>)>)