API reference

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

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.

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>
  • .build([callback]) ⇒ Promise.<Files>
  • .process([callback]) ⇒ Files
  • .run(files, plugins) ⇒ Object

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 | Object | Metalsmith

Optionally turn off frontmatter parsing.

Kind: instance method of Metalsmith

Example

metalsmith.frontmatter(false)  // turn off front-matter parsing
metalsmith.frontmatter()       // returns false

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