metalsmith
Advanced tools
An extremely simple, pluggable static site generator.
In Metalsmith, all of the logic is handled by plugins. You simply chain them together. Here's what the simplest blog looks like...
Metalsmith(__dirname)
.use(markdown())
.use(layouts('handlebars'))
.build(function (err) {
if (err) throw err
console.log('Build finished!')
})
...but what if you want to get fancier by hiding your unfinished drafts and using custom permalinks? Just add plugins...
Metalsmith(__dirname)
.use(drafts())
.use(markdown())
.use(permalinks('posts/:title'))
.use(layouts('handlebars'))
.build(function (err) {
if (err) throw err
console.log('Build finished!')
})
...it's as easy as that!
Special thanks to Ian Storm Taylor, Andrew Meyer, Dominic Barnes, Andrew Goodricke, Kevin Van Lierde and others for their contributions!
NPM:
npm install metalsmith
Yarn:
yarn add metalsmith
Check out the website for a list of plugins.
Metalsmith works in three simple steps:
Each plugin is invoked with the contents of the source directory, and each file can contain YAML front-matter that will be attached as metadata, so a simple file like...
---
title: A Catchy Title
date: 2021-12-01
---
An informative article.
...would be parsed into...
{
'path/to/my-file.md': {
title: 'A Catchy Title',
date: <Date >,
contents: <Buffer 7a 66 7a 67...>
}
}
...which any of the plugins can then manipulate however they want. And writing the plugins is incredibly simple, just take a look at the example drafts plugin.
Of course they can get a lot more complicated too. That's what makes Metalsmith powerful; the plugins can do anything you want!
We keep referring to Metalsmith as a "static site generator", but it's a lot more than that. Since everything is a plugin, the core library is actually just an abstraction for manipulating a directory of files.
Which means you could just as easily use it to make...
In addition to a simple Javascript API, the Metalsmith CLI can read configuration from a metalsmith.json file, so that you can build static-site generators similar to Jekyll or Wintersmith easily. The example blog above would be configured like this:
{
"source": "src",
"destination": "build",
"plugins": [
{ "@metalsmith/drafts": true },
{ "@metalsmith/markdown": true },
{ "@metalsmith/permalinks": "posts/:title" },
{ "@metalsmith/layouts": {} }
]
}
You can specify your plugins as either an object or array. Using an array would allow you to specify use of the same plugin multiple times. The above example is then defined as so:
{
"source": "src",
"destination": "build",
"plugins": [
{ "@metalsmith/drafts": true },
{ "@metalsmith/markdown": true },
{ "@metalsmith/permalinks": "posts/:title" },
{ "metalsmith-layouts": true }
]
}
And then just install metalsmith and the plugins and run the metalsmith CLI...
metalsmith
# Metalsmith · reading configuration from: /path/to/metalsmith.json
# Metalsmith · successfully built to: /path/to/build
Options recognised by metalsmith.json are source, destination, concurrency, metadata, clean and frontmatter - See "API" section below for usage.
Checkout the static site, Jekyll or Wintersmith examples to see the CLI in action.
If you want to use a custom plugin, but feel like it's too domain-specific to be published to the world, you can include plugins as local npm modules: (simply use a relative path from your root directory)
{
"plugins": [{ "./lib/metalsmith/plugin.js": true }]
}
Checkout the project scaffolder or build tool examples to see a real example of the Javascript API in use.
Create a new Metalsmith instance for a working dir.
Add the given plugin function to the middleware stack. Metalsmith uses
ware to support middleware, so plugins
should follow the same pattern of taking arguments of (files, metalsmith, callback),
modifying the files or metalsmith.metadata() argument by reference, and then
calling callback to trigger the next step.
Build with the given settings and a callback having signature fn(err, files).
Set the relative path to the source directory, or get the full one if no path is provided. The source directory defaults to ./src.
Set the relative path to the destination directory, or get the full one if no path is provided. The destination directory defaults to ./build.
Set the maximum number of files to open at once when reading or writing. Defaults to Infinity. To avoid having too many files open at once (EMFILE errors), set the concurrency to something lower than ulimit -n.
Set whether to remove the destination directory before writing to it, or get the current setting. Defaults to true.
Set whether to parse YAML frontmatter. Defaults to true.
Ignore files/paths from being loaded into Metalsmith.
path can be a string, a function, or an array of strings and/or functions.
Strings use the glob syntax from
minimatch to match files and directories
to ignore. Functions are called with the full path to the file as their first
argument, and the stat object returned by Node's fs.stat function as their
second argument, and must return either true to ignore the file, or false to
keep it.
Get the global metadata. This is useful for plugins that want to set global-level metadata that can be applied to all files.
Resolve any amount of paths... relative to the working directory. This is useful for plugins who want to read extra assets from another directory, for example ./layouts.
Run all of the middleware functions on a dictionary of files and callback with fn(err, files), where files is the altered dictionary.
Process the files like build without writing any files. Callback signature fn(err, files).
Add metadata to your files to access these build features. By default, Metalsmith uses a few different metadata fields:
contents - The body content of the file, not including any YAML frontmatter.mode - The numeric version of the file's mode.You can add your own metadata in two ways:
Set the mode of the file. For example, a cleanup.sh file with the contents
---
mode: 0764
---
#!/bin/sh
rm -rf .
would be built with mode -rwxrw-r--, i.e. user-executable.
Metalsmith 3.0.0 will support NodeJS versions 12 and higher. Metalsmith 2.4.0 supports NodeJS versions 8 and higher. Metalsmith 2.3.0 and below support NodeJS versions all the way back to 0.12.
[2.4.0] - 2022-01-31
Metalsmith#match method. Plugins no longer need to require a matching library 705c4bb, f01c724828b17efs.rm instead of rimraf when available (Node 14.4+) fcbb76e, 66e4376Metalsmith#frontmatter a6438d2ef7b7814eb1184Metalsmith#build now returns a promise which you can attach a then/catch to or await. The build callback model is still available. 6d5a42dDependencies: 75e6878
chalk: 1.1.3 ▶︎ 3.0.0gray-matter: 2.0.0 ▶︎ 4.0.3stat-mode: 0.2.0 ▶︎ 1.0.0rimraf: 2.2.8 ▶︎ 3.0.2ware: 1.2.0 ▶︎ 1.3.0commander (used in CLI): 2.15.1 ▶︎ 6.2.1win-fork (used in CLI): replaced with cross-spawn:7.0.3Updated CHANGELOG.md format to follow “Keep A Changelog” (#266) (@Zearin)
Metalsmith#ignore now only matches paths relative to Metalsmith#source (as it should). See linked issue for details 4eb1184Metalsmith#build a6438d2Metalsmith#ignore'd) 4eb1184Metalsmith#ignore now removes the matched files before they are statted for glob-based ignores (saving some perf & potential errors).new Buffer with Buffer.fromnpm audit vulnerability fixescoveralls: 2.11.6 ▶︎ 3.0.1 (#308) (@Zearin)
Fix 5 “Moderate” vulnerabilitiesmetalsmith-markdown: 0.2.1 ▶︎ 0.2.2 (#312) (@Zearin)
Fix 1 “Low” vulnerabilityFAQs
An extremely simple, pluggable static site generator.
The npm package metalsmith receives a total of 24,065 weekly downloads. As such, metalsmith popularity was classified as popular.
We found that metalsmith demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.