An extremely simple, pluggable static site generator.

Open issues
Closed issues
Last release
4 months ago
Last commit
4 months ago
Total releases
Total commits
Open PRs
Closed PRs
Repo URL
Offers premium version?


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:

import { fileURLToPath } from 'node:url'
import { dirname } from 'path'
import Metalsmith from 'metalsmith'
import layouts from '@metalsmith/layouts'
import markdown from '@metalsmith/markdown'

const __dirname = dirname(fileURLToPath(import.meta.url))

Metalsmith(__dirname) .use(markdown()) .use( layouts({ pattern: '*/.html' }) ) .build(function (err) { if (err) throw err console.log('Build finished!') })



npm install metalsmith


yarn add metalsmith

What if you want to get fancier by hiding unfinished drafts, grouping posts in collections, and using custom permalinks? Just add plugins...

import { fileURLToPath } from 'node:url'
import { dirname } from 'path'
import Metalsmith from 'metalsmith'
import collections from '@metalsmith/collections'
import layouts from '@metalsmith/layouts'
import markdown from '@metalsmith/markdown'
import permalinks from '@metalsmith/permalinks'

const __dirname = dirname(fileURLToPath(import.meta.url)) const t1 = const mode = process.env.NODE_ENV

Metalsmith(__dirname) // parent directory of this file .source('./src') // source directory .destination('./build') // destination directory .clean(true) // clean destination before .watch(mode === 'development') // rebuild on change in development .env({ // pass NODE_ENV & other environment variables DEBUG: process.env.DEBUG, NODE_ENV: mode }) .metadata({ // add any variable you want & use them in layout-files sitename: 'My Static Site & Blog', siteurl: '', description: "It's about saying »Hello« to the world.", generatorname: 'Metalsmith', generatorurl: '' }) .use( collections({ // group all blog posts by internally posts: 'posts/.md' // adding key 'collections':'posts' }) ) // use collections.posts in layouts .use(markdown()) // transpile all md into html .use( permalinks({ // change URLs to permalink URLs relative: false // put css only in /css }) ) .use( layouts({ pattern: '/.html' }) ) // wrap layouts around html .build((err) => { // build process if (err) throw err // error handling is required console.log(Build success in ${(( - t1) / 1000).toFixed(1)}s) })

How does it work?

Metalsmith works in three simple steps:

  1. Read all the files in a source directory.
  2. Invoke a series of plugins that manipulate the files.
  3. Write the results to a destination directory!

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/': {
    title: 'A Catchy Title',
    date: <Date >,
    contents: <Buffer 7a 66 7a 67...>,
    stats: {

...which any of the plugins can then manipulate however they want. Writing 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!


A Metalsmith plugin is a function that is passed the file list, the metalsmith instance, and a done callback. It is often wrapped in a plugin initializer that accepts configuration options.

Check out the official plugin registry at:
Find all the core plugins at:
See the draft plugin for a simple plugin example.


Check out the full API reference at:


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 Hexo easily. The example blog above would be configured like this:


  "source": "src",
  "destination": "build",
  "clean": true,
  "metadata": {
    "sitename": "My Static Site & Blog",
    "siteurl": "",
    "description": "It's about saying »Hello« to the world.",
    "generatorname": "Metalsmith",
    "generatorurl": ""
  "plugins": [
    { "@metalsmith/drafts": true },
    { "@metalsmith/collections": { "posts": "posts/*.md" } },
    { "@metalsmith/markdown": true },
    { "@metalsmith/permalinks": "posts/:title" },
    { "@metalsmith/layouts": true }

Then run:


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. Checkout the static site, Jekyll examples to see the CLI in action.

Local plugins

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 }]
The secret...

We often refer to Metalsmith as a "static site generator", but it's a lot more than that. Since everything is a plugin, the core library is just an abstraction for manipulating a directory of files.

Which means you could just as easily use it to make...



Use debug to debug your build with export DEBUG=metalsmith-*,@metalsmith/* (Linux) or set DEBUG=metalsmith-*,@metalsmith/* for Windows.
Use the excellent metalsmith-debug-ui plugin to get a snapshot UI for every build step.

Node Version Requirements

Future Metalsmith releases will at least support the oldest supported Node LTS versions.

Metalsmith 2.6.x supports NodeJS versions 14.14.0 and higher.
Metalsmith 2.5.x supports NodeJS versions 12 and higher.
Metalsmith 2.4.x supports NodeJS versions 8 and higher.
Metalsmith 2.3.0 and below support NodeJS versions all the way back to 0.12.

Compatibility & support policy

Metalsmith is supported on all common operating systems (Windows, Linux, Mac). Metalsmith releases adhere to semver (semantic versioning) with 2 minor gray-area exceptions for what could be considered breaking changes:

  • Major Node version support for EOL (End of Life) versions can be dropped in minor releases
  • If a change represents a major improvement that is backwards-compatible with 99% of use cases (not considering outdated plugins), they will be considered eligible for inclusion in minor version updates.


Special thanks to Ian Storm Taylor, Andrew Meyer, Dominic Barnes, Andrew Goodricke, Ismay Wolff, Kevin Van Lierde and others for their contributions!


Alternative Projects

Subscribe to Open Source Businees Newsletter

Twice a month we will interview people behind open source businesses. We will talk about how they are building a business on top of open source projects.

We'll never share your email with anyone else.