API reference

Checkout the project scaffolder or build tool examples to see a real example of the Javascript API in use.

Typedefs

MetalsmithMetalsmith

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

ParamType
directorystring

Properties

NameType
pluginsArray.<Plugin>
ignoresArray.<string>

metalsmith.use(plugin) ⇒ Metalsmith

Add a plugin function to the stack.

Kind: instance method of Metalsmith

ParamType
pluginPlugin

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

ParamType
[directory]string

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

ParamType
[metadata]Object

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

ParamType
[path]string

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

ParamType
[path]string

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

ParamType
[max]number

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

ParamType
[clean]boolean

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

ParamType
[frontmatter]boolean | GrayMatterOptions

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

ParamTypeDescription
[files]string | Array.<string>

The names or glob patterns of files or directories to ignore.

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

ParamType
...pathsstring

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

ParamTypeDescription
patternsstring | Array.<string>

one or more glob patterns

[input]Array.<string>

array of strings to match against

[value]string | number | boolean

value of the environment variable

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

ParamTypeDescription
[vars]string | Object

name of the environment variable, or an object with { name: 'value' } pairs

[value]string | number | boolean

value of the environment variable

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,
  ENV: 'development'
})

metalsmith.debug(namespace) ⇒ Debugger

Create a new debug debugger

Kind: instance method of Metalsmith

ParamTypeDescription
namespacestring

Debugger namespace

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

ParamType
[callback]BuildCallback

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

ParamType
[callback]BuildCallback

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

ParamType
filesFiles
pluginsArray.<Plugin>

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

NameTypeDescription
contentsBuffer

A NodeJS buffer that can be .toString'ed to obtain its human-readable contents

statsfs.Stats

A NodeJS fs.Stats object object with extra filesystem metadata and methods

modestring

Octal permission mode, see https://en.wikipedia.org/wiki/File-system_permissions#Numeric_notation

BuildCallback : function

A callback to run when the Metalsmith build is done

Kind: global typedef
this: {Metalsmith}

ParamType
[error]Error
filesFiles

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

ParamType
[error]Error

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

ParamType
filesFiles
metalsmithMetalsmith
doneDoneCallback

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

ParamTypeDescription
messagestring

Debug message, including formatter placeholders and an additional %b (buffer) formatter

...argsany

Arguments to fill the formatter placeholders with

Example

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

Methods

NameTypeDescription
warnfunction

Log a warning. Same signature as main debug function

errorfunction

Log an error. Same signature as main debug function

infofunction

Log an informational message. Same signature as main debug function

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'))
× This website may use local storage for purely functional purposes (for example to remember preferences), and anonymous cookies to gather information about how visitors use the site. By continuing to browse this site, you agree to its use of cookies and local storage.