API reference

Typedefs

Metalsmith ⇒ Metalsmith

Initialize a new Metalsmith builder with a working directory.

Files : Object.<string, File>

Metalsmith representation of the files in metalsmith.source(). The keys represent the file paths and the values are File objects

File : Object

Metalsmith file. Defines mode, stats and contents properties by default, but may be altered by plugins

BuildCallback : function

A callback to run when the Metalsmith build is done

DoneCallback : function

A callback to indicate that a plugin's work is done

Plugin : function

A Metalsmith plugin is a function that is passed the file list, the metalsmith instance, and a done callback. Calling the callback is required for asynchronous plugins, and optional for synchronous plugins.

Debugger : function

A debug-based plugin debugger

MatterOptions : Object

Options for parsing/stringifying front-and other matter

Metalsmith ⇒ Metalsmith

Initialize a new Metalsmith builder with a working directory.

Kind: global typedef

Properties

• Metalsmith ⇒ Metalsmith
  • .use(plugin) ⇒ Metalsmith
  • .directory([directory]) ⇒ string | Metalsmith
  • .metadata([metadata]) ⇒ Object | Metalsmith
  • .source([path]) ⇒ string | Metalsmith
  • .destination([path]) ⇒ string | Metalsmith
  • .concurrency([max]) ⇒ number | Metalsmith
  • .clean([clean]) ⇒ boolean | Metalsmith
  • .frontmatter([frontmatter]) ⇒ boolean | Metalsmith
  • .watch([options]) ⇒ boolean | Chokidar.WatchOptions | Metalsmith
  • .ignore([files]) ⇒ Metalsmith | Array.<string>
  • .path(…paths) ⇒ string
  • .match(patterns [, input [, options]]) ⇒ Array.<string>
  • .debug(namespace) ⇒ Debugger
  • .env([ vars [, value]]) ⇒ string | number | boolean | Object | Metalsmith
  • .build([callback]) ⇒ Promise.<Files> | void
  • .process([callback]) ⇒ Promise.<Files> | void
  • .run(files, plugins) ⇒ Promise.<Files> | void
  • .matter
    • .parse(contents) ⇒ File | void
    • .stringify(file) ⇒ string
    • .wrap(stringifiedData) ⇒ string

metalsmith.use(plugin) ⇒ Metalsmith

Add a plugin function to the stack.

Kind: instance method of Metalsmith

Example

metalsmith
 .use(drafts())   // use the drafts plugin
 .use(markdown()) // use the markdown plugin

metalsmith.directory([directory]) ⇒ string | Metalsmith

Get or set the working directory.

Kind: instance method of Metalsmith

Example

new Metalsmith('.')                   // set the path of the working directory through the constructor
metalsmith.directory()                // returns '.'
metalsmith.directory('./other/path')  // set the path of the working directory

metalsmith.metadata([metadata]) ⇒ Object | Metalsmith

Get or set the global metadata.

Kind: instance method of Metalsmith

Example

metalsmith.metadata({ sitename: 'My blog' });  // set metadata
metalsmith.metadata()                          // returns { sitename: 'My blog' }

metalsmith.source([path]) ⇒ string | Metalsmith

Get or set the source directory.

Kind: instance method of Metalsmith

Example

metalsmith.source('./src');    // set source directory
metalsmith.source()            // returns './src'

metalsmith.destination([path]) ⇒ string | Metalsmith

Get or set the destination directory.

Kind: instance method of Metalsmith

Example

metalsmith.destination('build'); // set destination
metalsmith.destination()         // returns 'build'

metalsmith.concurrency([max]) ⇒ number | Metalsmith

Get or set the maximum number of files to open at once.

Kind: instance method of Metalsmith

Example

metalsmith.concurrency(20)   // set concurrency to max 20
metalsmith.concurrency()     // returns 20

metalsmith.clean([clean]) ⇒ boolean | Metalsmith

Get or set whether the destination directory will be removed before writing.

Kind: instance method of Metalsmith

Example

metalsmith.clean(true)  // clean the destination directory
metalsmith.clean()      // returns true

metalsmith.frontmatter([frontmatter]) ⇒ boolean | Metalsmith

Optionally turn off frontmatter parsing or pass a gray-matter options object

Kind: instance method of Metalsmith

Example

metalsmith.frontmatter(false)  // turn off front-matter parsing
metalsmith.frontmatter()       // returns false
metalsmith.frontmatter({ excerpt: true })

metalsmith.watch([options]) ⇒ boolean | Chokidar.WatchOptions | Metalsmith

Partial rebuilding (=using metalsmith.watch with metalsmith.clean(false)) is still experimental and combined with @metalsmith/metadata <= 0.2.0 a bug may trigger an infinite loop. metalsmith.watch is incompatible with existing watch plugin. In watch mode, metalsmith.process/build are not awaitable. Callbacks passed to these methods will run on every rebuild instead of running once at the build's end.

Set the list of paths to watch and trigger rebuilds on. The watch method will skip files ignored with metalsmith.ignore() and will do partial (true) or full (false) rebuilds depending on the metalsmith.clean() setting. It can be used both for rebuilding in-memory with metalsmith.process or writing to file system with metalsmith.build.

Kind: instance method of Metalsmith

Example

metalsmith
  .ignore(['wont-be-watched'])  // ignored
  .clean(false)                 // do partial rebuilds
  .watch(true)                  // watch all files in metalsmith.source()
  .watch(['lib','src'])         // or watch files in directories 'lib' and 'src'

if (process.argv[2] === '--dry-run') {
  metalsmith.process(onRebuild) // reprocess in memory without writing to disk
} else {
  metalsmith.build(onRebuild)   // rewrite to disk
}

function onRebuild(err, files) {
  if (err) {
    metalsmith.watch(false)            // stop watching
     .finally(() => console.log(err))  // and log build error
  }
  console.log('reprocessed files', Object.keys(files).join(', '))
}

metalsmith.ignore([files]) ⇒ Metalsmith | Array.<string>

Get or set the list of filepaths or glob patterns to ignore

Kind: instance method of Metalsmith

Example

metalsmith.ignore()                      // return a list of ignored file paths
metalsmith.ignore('layouts')             // ignore the layouts directory
metalsmith.ignore(['.*', 'data.json'])   // ignore dot files & a data file

metalsmith.path(…paths) ⇒ string

Resolve paths relative to the metalsmith directory.

Kind: instance method of Metalsmith

Example

metalsmith.path('./path','to/file.ext')

metalsmith.match(patterns [, input [,options]]) ⇒ Array.<string>

Match filepaths in the source directory by glob pattern. If input is not specified, patterns are matched against Object.keys(files)

Kind: instance method of Metalsmith
Returns: Array.<string> - An array of matching file paths

metalsmith.env([vars [, value]]) ⇒ string | number | boolean | Object | Metalsmith

Get or set one or multiple metalsmith environment variables. Metalsmith env vars are case-insensitive.

Kind: instance method of Metalsmith

Example

// pass all Node env variables
metalsmith.env(process.env)
// get all env variables
metalsmith.env()
// get DEBUG env variable
metalsmith.env('DEBUG')
// set DEBUG env variable (chainable)
metalsmith.env('DEBUG', '*')
// set multiple env variables at once (chainable)
// this does not clear previously set variables
metalsmith.env({
  DEBUG: false,
  NODE_ENV: 'development'
})

metalsmith.debug(namespace) ⇒ Debugger

Create a new debug debugger

Kind: instance method of Metalsmith

Example

function plugin(files, metalsmith) {
  const debug = metalsmith.debug('metalsmith-myplugin')
  debug('a debug log')    // logs 'metalsmith-myplugin a debug log'
  debug.warn('A warning') // logs 'metalsmith-myplugin:warn A warning'
}

metalsmith.build([callback]) ⇒ Promise.<Files> | void

Build with the current settings to the destination directory.

Kind: instance method of Metalsmith
Fulfills: Files
Rejects: Error

Example

// callback variant
metalsmith.build(function(error, files) {
  if (error) throw error
  console.log('Build success!')
})

// promise variant
try {
  const files = await metalsmith.build()
  console.log('Build success')
} catch (error) {
  throw error
}

metalsmith.process([callback]) ⇒ Promise.<Files> | void

Process files through plugins without writing out files.

Kind: instance method of Metalsmith
Fulfills: Files
Rejects: Error

Example

// callback variant
metalsmith.process(err => {
  if (err) throw err
  console.log('Success')
})

// promise variant
try {
  await metalsmith.process()
  console.log('Success')
} catch (err) {
  throw err
}

metalsmith.run(files, plugins) ⇒ Object

Run a set of files through the plugins stack.

Kind: instance method of Metalsmith
Access: package

metalsmith.matter

Kind: instance member of Metalsmith

metalsmith.matter.options([options]) ⇒ void | MatterOptions

Get or set options for parsing & stringifying matter

Kind: instance method of Metalsmith.matter

Example

metalsmith.matter.parse(Buffer.from('---\ntitle: Hello World\n---\nIntro\n---')) === {
  contents: Buffer<'Hello world'>,
  title: 'Hello World',
  excerpt: 'Intro'
}

metalsmith.matter.parse(file) ⇒ File

Parse a string for front matter and return it as a File object.

Kind: instance method of Metalsmith.matter

Example

metalsmith.matter.parse(Buffer.from('---\ntitle: Hello World\n---\nIntro\n---')) === {
  contents: Buffer<'Hello world'>,
  title: 'Hello World',
  excerpt: 'Intro'
}

metalsmith.matter.stringify(file) ⇒ string

Stringify a File object to a string with frontmatter and contents

Kind: instance method of Metalsmith.matter

Example

metalsmith.matter.stringify({
  contents: Buffer.from('body'),
  title: 'Hello World',
  excerpt: 'Intro'
}) === [
  'title: Hello World',
  'excerpt: Intro',
  '---',
  'body'
].join('\n')

metalsmith.matter.wrap(stringifiedData) ⇒ string

Wrap stringified front-matter-compatible data with the matter delimiters

Kind: instance method of Metalsmith.matter

Example

metalsmith.matter.wrap(Buffer.from('{"hello": "world"}')) === '---\n{"hello": "world"}\n---'

Files : Object.<string, File>

Metalsmith representation of the files in metalsmith.source(). The keys represent the file paths and the values are File objects

Kind: global typedef

File

Metalsmith file. Defines mode, stats and contents properties by default, but may be altered by plugins

Kind: global typedef
Properties

BuildCallback : function

A callback to run when the Metalsmith build is done

Kind: global typedef
this: Metalsmith

Example

function onBuildEnd(error, files) {
  if (error) throw error
  console.log('Build success')
}

DoneCallback : function

A callback to indicate that a plugin’s work is done

Kind: global typedef

Example

function plugin(files, metalsmith, done) {
  // ..do stuff
  done()
}

Plugin : function

A Metalsmith plugin is a function that is passed the file list, the metalsmith instance, and a done callback. Calling the callback is required for asynchronous plugins, and optional for synchronous plugins.

Kind: global typedef

Example

function drafts(files, metalsmith) {
  Object.keys(files).forEach(path => {
    if (files[path].draft) {
      delete files[path]
    }
  })
}

metalsmith.use(drafts)

Debugger : function

A debug-based plugin debugger with warn, info and error channels.

Kind: global typedef

Example

const createDebugger = require('metalsmith/lib/debug')
const debugger = createDebugger('metalsmith-myplugin')
debugger('A message')

Methods

Example

const createDebugger = require('metalsmith/lib/debug')
const debugger = createDebugger('metalsmith-myplugin')
debugger.error('An error')
debugger.warn('A warning')
debugger.info('File contents: %b', Buffer.from('custom'))

MatterOptions: Object

Gray matter options

Kind: global typedef