API reference
Typedefs
- Metalsmith ⇒
Metalsmith
Initialize a new
Metalsmith
builder with a workingdirectory
.- 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
andcontents
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
Param | Type |
---|---|
directory | string |
Properties
Name | Type |
---|---|
plugins | Array.<Plugin> |
ignores | Array.<string> |
- 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
- .use(plugin) ⇒
metalsmith.use(plugin) ⇒ Metalsmith
Add a plugin
function to the stack.
Kind: instance method of Metalsmith
Param | Type |
---|---|
plugin | Plugin |
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
Param | Type |
---|---|
[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
Param | Type |
---|---|
[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
Param | Type |
---|---|
[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
Param | Type |
---|---|
[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
Param | Type |
---|---|
[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
Param | Type |
---|---|
[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
Param | Type |
---|---|
[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
Param | Type | Description |
---|---|---|
[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
Param | Type |
---|---|
...paths | string |
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
Param | Type | Description |
---|---|---|
patterns | string | 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
Param | Type | Description |
---|---|---|
[vars] | string | Object | name of the environment variable, or an object with |
[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,
NODE_ENV: 'development'
})
metalsmith.debug(namespace) ⇒ Debugger
Create a new debug debugger
Kind: instance method of Metalsmith
Param | Type | Description |
---|---|---|
namespace | string | 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
Param | Type |
---|---|
[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
Param | Type |
---|---|
[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
Param | Type |
---|---|
files | Files |
plugins | Array.<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
File
Metalsmith file. Defines mode
, stats
and contents
properties by default, but may be altered by plugins
Kind: global typedef
Properties
Name | Type | Description |
---|---|---|
contents | Buffer | A NodeJS buffer that can be |
stats | fs.Stats | A NodeJS fs.Stats object object with extra filesystem metadata and methods |
mode | string | 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}
Param | Type |
---|---|
[error] | Error |
files | Files |
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
Param | Type |
---|---|
[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
Param | Type |
---|---|
files | Files |
metalsmith | Metalsmith |
done | DoneCallback |
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
Param | Type | Description |
---|---|---|
message | string | Debug message, including formatter placeholders and an additional |
...args | any | Arguments to fill the formatter placeholders with |
Example
const createDebugger = require('metalsmith/lib/debug')
const debugger = createDebugger('metalsmith-myplugin')
debugger('A message')
Methods
Name | Type | Description |
---|---|---|
warn | function | Log a warning. Same signature as main debug function |
error | function | Log an error. Same signature as main debug function |
info | function | 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'))