Metalsmith works with all the tools and data formats you already know and use: NodeJS, npm, markdown, json, yaml and the templating language of your choice.


Metalsmith translates a directory tree to plain Javascript objects that you can manipulate effortlessly with your selection of plugins.


You shouldn't have to bend your project needs to a specific framework or tool. Metalsmith gives you full control of how you want to conceptualize, structure and build your project.


Use Metalsmith to generate anything from a static site, to a scaffolder, backup, command-line, or deploy tool. Configuration over code or code over configuration: Metalsmith supports both.

Install it

npm install metalsmith
yarn add metalsmith
pnpm add metalsmith

Or use a starter

Get the feel of it

You want to build a website or blog with a static site generator. Well, here is our elevator pitch. It’s as easy as that:

const Metalsmith  = require('metalsmith');
const collections = require('@metalsmith/collections');
const layouts     = require('@metalsmith/layouts');
const markdown    = require('@metalsmith/markdown');
const permalinks  = require('@metalsmith/permalinks');

Metalsmith(__dirname)         // __dirname defined by node.js:
                              // name of the directory of this file
  .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: ""
  .source('./src')            // source directory
  .destination('./build')     // destination directory
  .clean(true)                // clean destination before
  .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())             // wrap layouts around html
  .build(function(err) {      // build process
    if (err) throw err;       // error handling is required

The package exposes both a JavaScript API, and a CLI if you prefer. To see how they’re used check out the examples or the walkthrough.

You can follow along with a detailed walkthrough or have a go with a very minimal example:

git clone
cd metalsmith/examples/static-site
npm install
npm start

Build anything

We mainly 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…

Deploy anywhere

Metalsmith builds are static folders. They can be compressed, archived, deployed to a CDN, Netlify, Github Pages, Gitlab Pages, SFTP’d to a shared host, or SSH’d to a custom server.


Built with Metalsmith

Use a starter

× This website may use local storage for purely functional purposes (for example to remember preferences), and anonymous cookies to gather information about how visitors use the site. By continuing to browse this site, you agree to its use of cookies and local storage.