Key takeaway: The pitch is that a site build is just a pipeline of functions over a set of files, and if that idea appeals to you this is the purest expression of it. The catch is that you assemble everything yourself, including what Eleventy hands you free. Reach for it when your content workflow is genuinely unusual, not when you want a blog.
Quick facts
- LanguageJavaScript
- CategoryJS / TS plain
- LicenseMIT
- Created2014
- GitHub stars8.3k
- Statusmature
Templating: Handlebars Markdown Pug plugin-defined
What it is
Metalsmith treats site generation as a series of plugin transformations. Files in, plugins transform them, files out. Flexible, plugin-heavy, smaller community than Eleventy or Astro.
Best for
- Sites where the content workflow is non-standard
- Teams that want to compose their pipeline from small plugins
When not to pick it
For most projects Eleventy or Astro will serve you better with less plugin assembly.
My take
Powerful but uncommon choice in 2026. Eleventy and Astro have both improved their plugin stories enough that the original Metalsmith case is weaker than it was.
Files in, plugins over, files out
Metalsmith reads your source directory into a plain JavaScript object keyed by file path, hands that object to each plugin in turn, and writes the result out. That is the entire model, and its clarity is the appeal. There are no built-in ideas about collections, permalinks, layouts, or pagination, so nothing surprises you and nothing is hidden behind a convention you have to go looking for. For unusual pipelines this is liberating: pulling content from several sources, generating routes from an API response, emitting formats other than HTML, or applying a transformation nobody else has needed are all just functions you write. Because plugins are ordinary functions over a data structure you can inspect and log, debugging is unusually direct compared with generators that hide the work. If you like reading a build as a sequence of steps, you will enjoy this one.
The assembly cost, priced honestly
For a normal content site you will spend the first day wiring together plugins for Markdown, layouts, collections, permalinks, drafts, and assets, all of which Eleventy provides out of the box and Astro provides with a component model on top. A fair amount of the third-party plugin registry is lightly maintained, so expect to write or fork a few small ones, which is fine if you enjoy that and a poor use of a client budget if you do not. Development has settled into a maintenance pace rather than an expansion one. The compensating virtue is portability: because everything is plain JavaScript over a files object, understanding an inherited Metalsmith build is fast and moving content out of one is trivial. It is a tool for people who want to own their build, not for people who want a product.
Frequently asked questions
Is Metalsmith still maintained?
It receives maintenance but is not expanding, and part of the third-party plugin registry has gone stale. That is workable, because the core is small and stable and plugins are easy to write yourself. It is a poor bet if you need the tool to grow new capabilities alongside your project over the next few years.
Metalsmith or Eleventy?
Eleventy for almost every ordinary site: it gives you collections, pagination, the data cascade, and several template languages without assembly, and it has a far larger community. Metalsmith when the content pipeline itself is the unusual part and you would rather express it as explicit steps than fit it into someone else's conventions.
What is Metalsmith actually good at?
Non-standard transformations. Combining several content sources, generating pages from data that is not files, emitting output formats beyond HTML, or inserting a custom processing step at a specific point. Anywhere the interesting work is the pipeline rather than the templates, Metalsmith's model fits better than a conventions-driven generator.
Links
Similar tools you should also consider
If Metalsmith is your pick, the next conversation is short
The 30-min call is where your project gets a real architecture, an SEO transport plan, and a price range you can take to your team. Describe your site, your timeline, your existing content. I tell you whether Metalsmith is genuinely the right call for you, and what the build actually looks like.