Peter Morlion logo


Creating static sites with Metalsmith

Being a consultant, I am now the owner of a (humble) company. And a company should have a website, no? But this website doesn’t need to many bells and whistles, and I’m keeping my blog at, so a static html website would do.

I know about Jekyll, but it’s Ruby and I’m on Windows, and I know it’s possible, but it’s a bit of a hassle. I took a look at Brunch but it’s more of a general-purpose tool. This site finally pointed me to Metalsmith which works great.

Metalsmith is a pluggable static site generator that is more than a static site generator. Every step is just a plugin and you feed every plugin source files and do whatever you want with it. So it can do more than just generate a static html site. But I’m happy with just the generation aspect of it, so here’s how I set it up.

Create your project directory and install metalsmith through npm:

npm install metalsmith --save-dev

It’s also handy to install globally, as Metalsmith includes a CLI:

npm install -g metalsmith

In the root of your folder, create a metalsmith.json file with the following contents:

    "source": "src",
    "destination": "build",
    "plugins": {
        "metalsmith-drafts": true,
        "metalsmith-markdown": true,
        "metalsmith-layouts": {
            engine: "handlebars"

This means Metalsmith will take the files in the src directory and pass them through the listed plugins. The results will be put in the destination folder. Simple, no?

The plugins that are listed do the following:

Now, create a simple file in the src directory:

title: My Homepage
draft: false
layout: layout.html
Welcome to my homepage!

This will be converted to the following javascript object:

    title: 'My Homepage',
    draft: false,
    layout: 'layout.html',
    contents: new Buffer('Welcome to my homepage!')

Don’t worry about the Buffer part. It’s enough to know that you have access to the contents of the markdown file. This allows you to specify a layout.html file in the layouts directory (a convention used by the metalsmith-layouts plugin):

<!doctype html>

Now, at the command-line, just run:


And you will see your index.html in the build folder! From there on, there’s a myriad of possibilities (check out the plugins list).

For me, the most important thing now is that I can quickly and easily create a static html site, without setting up complicated or verbose configuration files, or jumping through hoops to get certain things installed.

If you’re interested in a more complex example (which is still evolving right now), check out my first site I’m creating with Metalsmith.

update: My company’s site is now online at

One Response

Leave a Reply

Your email address will not be published. Required fields are marked *