Metalsmith — Pluggable Static Site Generator for Node.js

Introduction

Metalsmith reduces static site generation to its simplest form: read files from a source directory, run them through a series of plugins, and write the results to a destination directory. Every feature — Markdown conversion, templating, permalinks, metadata — is a plugin. This makes Metalsmith highly flexible: you can build a blog, a documentation site, or a custom data pipeline just by choosing which plugins to chain together.

What Metalsmith Does

• Reads a directory of source files into an in-memory file tree with metadata
• Passes the file tree through a chain of plugins, each transforming files as needed
• Supports YAML front matter for per-file metadata
• Writes the transformed files to a build directory
• Works as both a CLI tool and a programmatic Node.js API

Architecture Overview

Metalsmith represents each source file as a JavaScript object containing a contents Buffer and any YAML front matter as properties. The build pipeline is a sequence of plugin functions, each receiving the full file tree and metadata. Plugins can add, modify, rename, or remove files. After all plugins run, the final file tree is written to disk. This simple contract — function(files, metalsmith, done) — means any transformation that operates on files can be a Metalsmith plugin.

Self-Hosting & Configuration

• Install metalsmith and the plugins you need via npm
• Create a build script using the Metalsmith API or configure via metalsmith.json
• Place source files (Markdown, HTML, data) in the src/ directory
• Chain plugins with .use() in the order they should execute
• Run the build script to generate the site in the build/ directory

Key Features

• Extremely simple core: the engine is under 500 lines of code
• Plugin-based architecture with 200+ community plugins available
• Works with any template engine via metalsmith-layouts (Handlebars, Pug, Nunjucks, EJS)
• YAML front matter support for per-file metadata and configuration
• Usable both as a Node.js API and a CLI tool with JSON config

Comparison with Similar Tools

• Eleventy — also plugin-based with more built-in data features; Metalsmith is lower-level with a simpler core
• Hugo — written in Go with built-in templating and speed; Metalsmith is JavaScript-native and fully extensible
• Jekyll — Ruby-based with convention-over-configuration; Metalsmith requires explicit plugin selection
• Gulp — general-purpose task runner; Metalsmith is purpose-built for file transformation pipelines

FAQ

Q: Is Metalsmith suitable for large sites? A: Yes, but since it loads all files into memory, very large sites (tens of thousands of pages) may benefit from incremental builds or a streaming alternative.

Q: How do I add a blog to a Metalsmith site? A: Use metalsmith-collections to group posts, metalsmith-markdown for content, metalsmith-permalinks for clean URLs, and metalsmith-layouts for templates.

Q: Can I use it with modern JavaScript and ES modules? A: Yes. Metalsmith v2.6+ supports ESM imports, and you can use any modern JavaScript in your build scripts and plugins.

Q: How do I create a custom plugin? A: A plugin is a function returning function(files, metalsmith, done). Modify the files object as needed and call done() when finished.

Sources

• https://github.com/metalsmith/metalsmith
• https://metalsmith.io