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

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

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
  • .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

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.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>

Build with the current settings to the destination directory.

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

Example

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

metalsmith.process([callback]) ⇒ Files

Process files through plugins without writing out files.

Kind: instance method of Metalsmith

Example

metalsmith.process(err => {
  if (err) throw err
  console.log('Success')
  console.log(this.metadata())
})

metalsmith.run(files, plugins) ⇒ Object

Run a set of files through the plugins stack.

Kind: instance method of Metalsmith
Access: package

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'))