Building this site with Metalsmith


For years my portfolio site ran on the Drupal CMS. Periodically I would upgrade to address some important security fix, and inevitably a major upgrade would come along causing untold headaches with the fragile ecosystem of modules that ceased to operate correctly. Enter static site generators and Metalsmith in particular.


I recently found a need to move my portfolio content over to a more portable system after years of using Drupal. The massive growth of static site generators seems to indicate that, like me, many others feel the need for something more lightweight and agile.

Pros And Cons: Static Site vs. CMS

In favor of Metalsmith and static site generators

  • Pages load fast. There's no need to hit a DB, perform lookups, aggregate the content. Everything in a static site is pre-baked.
  • Security is no longer an issue. With no admin login to do remote edits, there's a much smaller attack surface for your site.
  • Markdown is practically the defacto content standard for documents in most static site generators, meaning if you're not satisfied with one, you can easily port to another. Moving the content across is virtually a non issue.
  • Here are some of my reasons for choosing Metalsmith:

    • The ability to use JavaScript and node.js as the backing technology. If I want to customize the behavior, it's easy to do.
    • I really appreciate the underlying ethos of Metalsmith, which is essentially just a file processor, stepping systematically over files one at a time and layering up functionality a plugin at a time. This does mean that barebones Metalsmith has a small but slightly steep learning curve. I found the initial effort was soon rewarded however and I'm glad I stayed the course with it.
    • Writing plugins for Metalsmith is incredibly easy. Here's one I use for debugging:

      // Simple Debugging Plugin
      var plugin = function (options) {
          return function (files, metalsmith, done) {
              // console.log(files);
              _.each(metalsmith._metadata.collections.projects, function (item) {
  • Your markup is completely transparent via the templating system you choose and as a result, theming is pleasant.

  • Build process is very fast.

In favor of Drupal or similar CMS

  • You can edit your site remotely. There are solutions to do this with Metalsmith, but it's not a primary use case and it's just something that is done better with a full fledged CMS
  • Drupal comes with pretty decent forum and comment functionality out of the box. I've seen a lot of other Metalsmith users integrate with disqus. It's not something I need however.
  • You can set up all kinds of feeds for your content, out of the box. This is not something I currently need.

Some tips when starting out with Metalsmith:

  • In order to get metalsmith working I had to add the -harmony CLI switch for node 0.12.7 .
  • Excerpts works with HTML not markdown as stated.
  • Creating links required use of the metalsmith-permalink plugin, in the context of metalsmith-collections .
  • Must require all the dependencies before using them.
  • Handlebars partials work well as includes, good for scripts / css / meta sections as well as header/footer blocks.

    Here's how I'm using partials for common reusable page sections:

    // Implement Header and footer through handlebars partials
    handlebars.registerPartial('header', fs.readFileSync(__dirname + '/templates/partials/header.html').toString());
    handlebars.registerPartial('footer', fs.readFileSync(__dirname + '/templates/partials/footer.html').toString());
    handlebars.registerPartial('css', fs.readFileSync(__dirname + '/templates/partials/css.html').toString());
    handlebars.registerPartial('meta', fs.readFileSync(__dirname + '/templates/partials/meta.html').toString());