metalsmith

constructor

constructor(directory: string);

• Initialize a new Metalsmith builder with a working directory.

property debug

debug: {
    (namespace: string): Metalsmith.Debugger;
    enable(namespaces: string): void;
    disable(): void;
    handle(...args: any[]): void;
    colors: boolean;
    enabled: boolean;
};

• Initialize a plugin [API Docs](https://metalsmith.io/api/#Metalsmith+debug) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/debug.js)

  Example 1

  const debugger = metalsmith.debug('metalsmith-myplugin')

  debug('a log') // logs 'metalsmith-myplugin a log' debug.info('an info') // logs 'metalsmith-myplugin:info an info' debug.warn('a warning') // logs 'metalsmith-myplugin:warn a warning' debug.error('an error') // logs 'metalsmith-myplugin:error an error'

property ignores

readonly ignores: string[];

• The (read-only) list of ignores of the current metalsmith instance

property matter

matter: {
    options(): Metalsmith.MatterOptions;
    options(options: Metalsmith.MatterOptions): void;
    parse(contents: Buffer | string): Metalsmith.File;
    stringify(file: Metalsmith.File): string;
    wrap(stringifiedData: Buffer | string): string;
};

property plugins

readonly plugins: Metalsmith.Plugin[];

• The (read-only) list of plugins use'd by the current metalsmith instance. When read from inside a plugin, the list is guaranteed to be complete

method build

build: { (): Promise<Metalsmith.Files>; (callback: Metalsmith.Callback): void };

• Perform the build with the current settings outputting to . [API Docs](https://metalsmith.io/api/#Metalsmith+build) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L407)

  Example 1

  metalsmith.build() .then(files => console.log(Build success. Processed ${files.length})) .catch(err => { throw err })

• Perform the build with the current settings outputting to . [API Docs](https://metalsmith.io/api/#Metalsmith+build) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L407)

  Example 1

  metalsmith.build((err, files) => { if (err) throw err console.log(Build success. Processed ${files.length}) });

method clean

clean: { (clean: boolean): Metalsmith; (): boolean };

• Set whether will be cleaned before writing. Defaults to true. [API Docs](https://metalsmith.io/api/#Metalsmith+clean) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L270) true

  Example 1

  metalsmith.clean(false)

• Get whether the destination directory will be cleaned before writing. [API Docs](https://metalsmith.io/api/#Metalsmith+clean) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L270)

  Example 1

  const clean = metalsmith.clean()

method concurrency

concurrency: { (max: number): Metalsmith; (): number };

• Set the max number of files to open at once. Useful if you encounter EMFILE errors, see [Node.js docs](https://nodejs.org/api/errors.html#errors_common_system_errors) [API Docs](https://metalsmith.io/api/#Metalsmith+concurrency) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L253) Infinity

  Example 1

  metalsmith.concurrency(50)

• Get the max number of files to open at once. [API](https://metalsmith.io/api/#Metalsmith+concurrency) | [Source](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L253)

  Example 1

  const max = metalsmith.concurrency()

method destination

destination: { (path: string): Metalsmith; (): string };

• Set the path of the destination directory. [API Docs](https://metalsmith.io/api/#Metalsmith+destination) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L235) 'build'

  Example 1

  metalsmith.destination('build');

• Get the absolute path of the destination directory. [API Docs](https://metalsmith.io/api/#Metalsmith+destination) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L235)

  Example 1

  const dest = metalsmith.destination()

method directory

directory: { (directory: string): Metalsmith; (): string };

• Set the working directory. Relative paths resolve to process.cwd() [API Docs](https://metalsmith.io/api/#Metalsmith+directory) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L181)

  Example 1

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

• Get the absolute path of the working directory. [API Docs](https://metalsmith.io/api/#Metalsmith+directory) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L181)

  Example 1

  const msdir = metalsmith.directory();

method env

env: {
    (name: string): number | boolean | string | null;
    (): Object;
    (name: string, value: string | number | boolean): Metalsmith;
    (env: { [key: string]: string | number | boolean }): Metalsmith;
};

• Get a single metalsmith environment variable. Metalsmith env vars are case-insensitive. [API Docs](https://metalsmith.io/api/#Metalsmith+env) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L372)

  Example 1

  const env = metalsmith.env('NODE_ENV') if (env === 'development') { ... }

• Get all metalsmith environment variables. Metalsmith env vars are returned in capital-case. [API Docs](https://metalsmith.io/api/#Metalsmith+env) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L372)

  Example 1

  const env = metalsmith.env(); console.log(env) // { NODE_ENV: 'development' }

• Set a single metalsmith environment variable (chainable). Metalsmith env vars are case-insensitive. [API Docs](https://metalsmith.io/api/#Metalsmith+env) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L372)

  Example 1

  metalsmith .env('NODE_ENV', process.env.NODE_ENV) .env('DEBUG', '@metalsmith/*')

• Add multiple metalsmith environment variables at once (chainable). Metalsmith env vars are case-insensitive. This signature will overwrite but not remove existing metalsmith environment variables [API Docs](https://metalsmith.io/api/#Metalsmith+env) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L372)

  Example 1

  metalsmith.env({ NODE_ENV: process.env.NODE_ENV, DEBUG: '@metalsmith/*' })

method frontmatter

frontmatter: { (frontmatter?: boolean | {}): Metalsmith; (): boolean };

• Set the flag on whether to parse YAML frontmatter [API Docs](https://metalsmith.io/api/#Metalsmith+frontmatter) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L291) true

  Example 1

  metalsmith.frontmatter(false);

• Get the flag on whether to parse YAML frontmatter [API Docs](https://metalsmith.io/api/#Metalsmith+frontmatter) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L291)

  Example 1

  const on = metalsmith.frontmatter() // true or false

method ignore

ignore: {
    (
        files: string | string[] | Metalsmith.Ignore | Metalsmith.Ignore[]
    ): Metalsmith;
    (): string[];
};

• Set the files/paths to ignore loading into Metalsmith. [API Docs](https://metalsmith.io/api/#Metalsmith+ignore) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L316)

  Example 1

  metalsmith.ignore("corrupted.html"); metalsmith.ignore(function (filepath: string, stats: Stats) { return stats.isDirectory() && path.basename(filepath) === 'nested'; });

• Get the array of files/paths. [API Docs](https://metalsmith.io/api/#Metalsmith+ignore) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L316)

  Example 1

  const ignored = metalsmith.ignore();

method match

match: (
    pattern: string | string[],
    input?: string[],
    options?: Omit<micromatch.Options, 'format'>
) => string[];

• Match filepaths in the source directory by [glob](https://en.wikipedia.org/wiki/Glob_(programming)) pattern. If input is not specified, patterns are matched against Object.keys(files) [API Docs](https://metalsmith.io/api/#Metalsmith+match) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L346)

  Example 1

  // match all .html files at the source dir root but omit files starting with a dot: metalsmith.match('*.html', Object.keys(files), { dot: false })

method metadata

metadata: { (metadata: object): Metalsmith; (): object };

• Assign values to the global metadata object. [API Docs](https://metalsmith.io/api/#Metalsmith+metadata) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L199)

  Example 1

  metalsmith.metadata({ sitename: "My Static Site", baseurl: process.env.NODE_ENV === 'development' ? 'http://localhost:8080' : 'https://johndoe.com' });

• Get the global metadata object. [API Docs](https://metalsmith.io/api/#Metalsmith+metadata) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L199)

  Example 1

  const metadata = metalsmith.metadata();

method path

path: (...paths: string[]) => string;

• Resolve paths relative to the root directory. [API Docs](https://metalsmith.io/api/#Metalsmith+path) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L332)

  Example 1

  const path = metalsmith.path("./dist", "assets");

method process

process: {
    (): Promise<Metalsmith.Files>;
    (callback: Metalsmith.Callback): void;
};

• Process files through without writing out files. [API Docs](https://metalsmith.io/api/#Metalsmith+process) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L549)

  Example 1

  metalsmith.process() .then(files => console.log(Done processing ${files.length} files.)) .catch(err => { throw err })

• Process files through without writing out files. [API Docs](https://metalsmith.io/api/#Metalsmith+process) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L549)

  Example 1

  metalsmith.process((err, files) => { if (err) throw err console.log(Done processing ${files.length} files.)) })

method read

read: {
    (dir?: string): Promise<Metalsmith.Files>;
    (dir: string, callback: Metalsmith.Callback): void;
};

• Read a dictionary of files from a dir, parsing frontmatter *(promise variant)*. If no directory is provided, it will default to . [API Docs](https://metalsmith.io/api/#Metalsmith+read) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L625)

  Example 1

  metalsmith.read('relative/to/msdir') .then(files => console.log(files)) .catch(err => { throw err })

• Read a dictionary of files from a dir, parsing frontmatter. If no directory is provided, it will default to . [API Docs](https://metalsmith.io/api/#Metalsmith+read) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L625)

  Example 1

  metalsmith.read('relative/to/msdir', (err, files) => { if (err) throw err console.log(files) });

method readFile

readFile: {
    (file: string): Promise<Metalsmith.File>;
    (
        file: string,
        callback: (
            err: Error,
            file?: Metalsmith.File<Record<string, unknown>>
        ) => void
    ): void;
};

• Read a file by path. Relative paths resolve to . [API Docs](https://metalsmith.io/api/#Metalsmith+readFile) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L663)

  Example 1

  metalsmith.readFile('index.md') .then(file => { const { contents, stat, mode, ...metadata } = file }) .catch(err => { throw err });

• Read a file by path. Relative paths resolve to . [API Docs](https://metalsmith.io/api/#Metalsmith+readFile) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L663)

  Example 1

  metalsmith.readFile("a.html", (err, file) => { if (err) throw err const { contents, stat, mode, ...metadata } = file });

method run

run: {
    (files: Metalsmith.Files, callback: Metalsmith.Callback): void;
    (
        files: Metalsmith.Files,
        plugins: Metalsmith.Plugin[],
        callback: Metalsmith.Callback
    ): void;
    (
        files: Metalsmith.Files,
        plugins?: Metalsmith.Plugin[]
    ): Promise<Metalsmith.Files>;
};

• Run a set of files through the plugins stack. [API Docs](https://metalsmith.io/api/#Metalsmith+run) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L581)

  Example 1

  const file = { contents: Buffer.from('contents') } metalsmith.run({ 'index.html': file } , (err, files) => { if (err) {throw err;}});

• Run a set of files through the plugins stack. [API Docs](https://metalsmith.io/api/#Metalsmith+run) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L581)

  Example 1

  const file = { contents: Buffer.from('contents') } metalsmith.run({ 'index.html': file }, metalsmith.plugins, (err, files) => { if (err) {throw err;}});

• Run a set of files through the plugins stack. [API Docs](https://metalsmith.io/api/#Metalsmith+run) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L581)

  Example 1

  const file = { contents: Buffer.from('contents') } metalsmith.run({ 'index.html': file }, metalsmith.plugins) .then(files => {}) .catch(err => { if (err) {throw err;}});

method source

source: { (path: string): Metalsmith; (): string };

• Set the path of the source directory, relative to metalsmith.directory() [API Docs](https://metalsmith.io/api/#Metalsmith+source) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L217) 'src'

  Example 1

  metalsmith.source('src');

• Get the absolute path of the source directory. [API](https://metalsmith.io/api/#Metalsmith+source) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L217)

  Example 1

  const src = metalsmith.source();

method use

use: (plugin: Metalsmith.Plugin | Metalsmith.Plugin[]) => Metalsmith;

• Add a plugin function to the stack. [API Docs](https://metalsmith.io/api/#Metalsmith+use) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L164)

  Example 1

  import markdown from '@metalsmith/markdown' metalsmith.use(markdown({ gfm: true }))

method watch

watch: {
    (): false | WatchOptions;
    (
        watch:
            | string
            | boolean
            | string[]
            | Omit<
                  WatchOptions,
                  'ignoreInitial' | 'ignored' | 'alwaysStat' | 'cwd'
              >
    ): Metalsmith;
};

• Consult [chokidar.watchOptions](https://github.com/paulmillr/chokidar#api) in use by metalsmith.watch. [API Docs](https://metalsmith.io/api/#Metalsmith+watch) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L510)

  Example 1

  metalsmith.watch() // { // paths: [metalsmith.source()], // ignoreInitial: true, // awaitWriteFinish: false, // ignore: metalsmith.ignore(), // alwaysStat: false // }

• Set the list of paths to watch and trigger rebuilds on. The watch method will skip files ignored with and will do partial (true) or full (false) rebuilds depending on the setting. It can be used both for rebuilding in-memory with or writing to file system with . [API Docs](https://metalsmith.io/api/#Metalsmith+watch) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L510) false

  Example 1

  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'

method write

write: {
    (files: Metalsmith.Files, dir: string, callback: Metalsmith.Callback): void;
    (files: Metalsmith.Files, callback: Metalsmith.Callback): void;
    (files: Metalsmith.Files, dir?: string): Promise<void>;
};

• Write an object of to a destination dir. Relative paths resolve to . [API Docs](https://metalsmith.io/api/#Metalsmith+write) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L719)

  Example 1

  const files = { 'index.html': { contents: Buffer.from('...') } } metalsmith.write(files, metalsmith.path("./dist"));

• Write an object of to a destination dir. Relative paths resolve to . [API Docs](https://metalsmith.io/api/#Metalsmith+write) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L719)

  Example 1

  metalsmith.write({fileA: "a.html"} , metalsmith.path("./dist"));

• Write an object of to a destination dir. Relative paths resolve to . [API Docs](https://metalsmith.io/api/#Metalsmith+write) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L719)

  Example 1

  const file = { contents: Buffer.from('...') metalsmith.write({ 'index.html': file }) .then(() => console.log('Files written')) .catch(err => { throw err })

method writeFile

writeFile: {
    (filepath: string, data: Metalsmith.File): Promise<void>;
    (
        filepath: string,
        data: Metalsmith.File<Record<string, unknown>>,
        callback: (error: Error) => void
    ): void;
};

• Write to filepath. Relative paths resolve to . [API Docs](https://metalsmith.io/api/#Metalsmith+writeFile) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L650)

  Example 1

  const file = { contents: Buffer.from('File Contents') } metalsmith.writeFile("test.html", file) .then(() => console.log('File written')) .catch(err => { throw err })

• Write to filepath. Relative paths resolve to . [API Docs](https://metalsmith.io/api/#Metalsmith+writeFile) | [Source code](https://github.com/metalsmith/metalsmith/blob/v2.6.0/lib/index.js#L650)

  Example 1

  const file = { contents: Buffer.from('File Contents') } metalsmith.writeFile("test.html", file, (err) => { if (err) throw err console.log('File written') })

property error

error: DebugDebugger;

property info

info: DebugDebugger;

property warn

warn: DebugDebugger;

index signature

[filepath: string]: File;

property delimiters

delimiters?: string | string[];

property engines

engines?: {
    [engine: string]:
        | ((file: string) => any)
        | {
              parse: (file: string) => any;
              stringify?: (data: any) => string;
          };
};

property excerpt

excerpt?:
    | boolean
    | ((file: GrayMatterFile<string>, options: Metalsmith.MatterOptions) => {});

property excerpt_separator

excerpt_separator?: string;

property language

language?: string;