# Metalsmith — Pluggable Static Site Generator for Node.js

> An extremely simple static site generator that treats everything as a plugin, letting you compose a custom build pipeline from a library of community plugins for Markdown, templates, layouts, and more.

## Install

Save in your project root:

# Metalsmith — Pluggable Static Site Generator for Node.js

## Quick Use
```bash
npm install metalsmith metalsmith-markdown metalsmith-layouts
```
```js
const Metalsmith = require('metalsmith');
const markdown = require('metalsmith-markdown');
const layouts = require('metalsmith-layouts');

Metalsmith(__dirname)
  .source('./src')
  .destination('./build')
  .use(markdown())
  .use(layouts({ engine: 'handlebars' }))
  .build((err) => { if (err) throw err; });
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-4a811a16
Author: AI Open Source