Metalsmith

An extremely simple, pluggable static site generator.

Star on GitHub

Everything is a Plugin

All of the logic in Metalsmith is handled by plugins. You simply chain them together. Here’s what the simplest blog looks like…

Metalsmith(__dirname)
  .use(markdown())
  .use(templates('handlebars'))
  .build();

…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(templates('handlebars'))
  .build();

…it’s as easy as that!


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, with every file parsed for optional YAML front-matter, like so…

---
title: A Catchy Title
draft: true
---

An unfinished article...
{
  'path/to/my-file.md': {
    title: 'A Catchy Title',
    draft: true,
    contents: new Buffer('An unfinished article...')
  }
}

The plugins can manipulate the files however they want, and writing one is super simple. Here’s the code for the drafts plugin from above:

function(){
  return function drafts(files, metalsmith, done){
    for (var file in files) {
      if (files[file].draft) delete files[file];
    }
    done();
  };
}

Of course they can get a lot more complicated too. That’s what makes Metalsmith powerful; the plugins can do anything you want.


Install it

Metalsmith and its plugins can be installed with npm:

$ npm install metalsmith

The package exposes both a Javascript API, and CLI in case you’re used to that type of workflow from other static site generators. To see how they’re used check out the examples.


A Little Secret

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…

The plugins are all reusable. That PDF generator plugin for eBooks? Use it to generate PDFs for each of your blog posts too!

Check out the code examples to get an idea for what’s possible.


The Plugins

The core Metalsmith library doesn’t bundle any plugins by default. You just require new ones as needed, or make your own!

Here’s a list of the current plugins:

If you write your own plugin, submit a pull request to the metalsmith.io repository and it will show up here!