metalsmith

Metalsmith

An extremely simple, pluggable static site generator.

In Metalsmith, all of the logic is handled by plugins. You simply chain them together.

Here's what the simplest blog looks like:

const Metalsmith = require('metalsmith')
const layouts = require('@metalsmith/layouts')
const markdown = require('@metalsmith/markdown')

Metalsmith(__dirname)
  .use(markdown())
  .use(layouts())
  .build(function (err) {
    if (err) throw err
    console.log('Build finished!')
  })

Installation

NPM:

npm install metalsmith

Yarn:

yarn add metalsmith

Quickstart

What if you want to get fancier by hiding unfinished drafts, grouping posts in collections, and using custom permalinks? Just add plugins...

const Metalsmith = require('metalsmith')
const collections = require('@metalsmith/collections')
const layouts = require('@metalsmith/layouts')
const markdown = require('@metalsmith/markdown')
const permalinks = require('@metalsmith/permalinks')

Metalsmith(__dirname)
  .source('./src')
  .destination('./build')
  .clean(true)
  .frontmatter({
    excerpt: true
  })
  .env({
    NAME: process.env.NODE_ENV,
    DEBUG: '@metalsmith/*',
    DEBUG_LOG: 'metalsmith.log'
  })
  .metadata({
    sitename: 'My Static Site & Blog',
    siteurl: 'https://example.com/',
    description: "It's about saying »Hello« to the world.",
    generatorname: 'Metalsmith',
    generatorurl: 'https://metalsmith.io/'
  })
  .use(
    collections({
      posts: 'posts/*.md'
    })
  )
  .use(markdown())
  .use(
    permalinks({
      relative: false
    })
  )
  .use(layouts())
  .build(function (err) {
    if (err) throw err
  })

How does it work?

Metalsmith works in three simple steps:

1. Read all the files in a source directory.
2. Invoke a series of plugins that manipulate the files.
3. Write the results to a destination directory!

Each plugin is invoked with the contents of the source directory, and each file can contain YAML front-matter that will be attached as metadata, so a simple file like...

---
title: A Catchy Title
date: 2021-12-01
---

An informative article.

...would be parsed into...

{
  'path/to/my-file.md': {
    title: 'A Catchy Title',
    date: <Date >,
    contents: <Buffer 7a 66 7a 67...>,
    stats: {
      ...
    }
  }
}

...which any of the plugins can then manipulate however they want. Writing plugins is incredibly simple, just take a look at the example drafts plugin.

Of course they can get a lot more complicated too. That's what makes Metalsmith powerful; the plugins can do anything you want!

Plugins

A Metalsmith plugin is a function that is passed the file list, the metalsmith instance, and a done callback. It is often wrapped in a plugin initializer that accepts configuration options.

Check out the official plugin registry at: https://metalsmith.io/plugins.
Find all the core plugins at: https://github.com/search?q=org%3Ametalsmith+metalsmith-plugin
See the draft plugin for a simple plugin example.

API

Check out the full API reference at: https://metalsmith.io/api.

CLI

In addition to a simple Javascript API, the Metalsmith CLI can read configuration from a metalsmith.json file, so that you can build static-site generators similar to Jekyll or Hexo easily. The example blog above would be configured like this:

metalsmith.json

{
  "source": "src",
  "destination": "build",
  "clean": true,
  "metadata": {
    "sitename": "My Static Site & Blog",
    "siteurl": "https://example.com/",
    "description": "It's about saying »Hello« to the world.",
    "generatorname": "Metalsmith",
    "generatorurl": "https://metalsmith.io/"
  },
  "plugins": [
    { "@metalsmith/drafts": true },
    { "@metalsmith/collections": { "posts": "posts/*.md" } },
    { "@metalsmith/markdown": true },
    { "@metalsmith/permalinks": "posts/:title" },
    { "@metalsmith/layouts": true }
  ]
}

Then run:

metalsmith

# Metalsmith · reading configuration from: /path/to/metalsmith.json
# Metalsmith · successfully built to: /path/to/build

Options recognised by metalsmith.json are source, destination, concurrency, metadata, clean and frontmatter. Checkout the static site, Jekyll examples to see the CLI in action.

Local plugins

If you want to use a custom plugin, but feel like it's too domain-specific to be published to the world, you can include plugins as local npm modules: (simply use a relative path from your root directory)

{
  "plugins": [{ "./lib/metalsmith/plugin.js": true }]
}

The secret...

We often refer to Metalsmith as a "static site generator", but it's a lot more than that. Since everything is a plugin, the core library is just an abstraction for manipulating a directory of files.

Which means you could just as easily use it to make...

• A project scaffolder.
• A build tool for Sass files.
• A simple static site generator.
• A Jekyll-like static site generator.

Resources

• Gitter community chat for chat, questions
• Twitter announcements and the metalsmith.io news page for updates
• Awesome Metalsmith - great collection of resources, examples, and tutorials
• emmer.dev on metalsmith - A good collection of various how to's for metalsmith
• glinka.co on metalsmith - Another great collection of advanced approaches for developing metalsmith
• Getting to Know Metalsmith - a great series about how to use Metalsmith for your static site.

Troubleshooting

Use debug to debug your build with export DEBUG=metalsmith-*,@metalsmith/* (Linux) or set DEBUG=metalsmith-*,@metalsmith/* for Windows.
Use the excellent metalsmith-debug-ui plugin to get a snapshot UI for every build step.

Node Version Requirements

Metalsmith 2.5.x supports NodeJS versions 12 and higher.
Metalsmith 2.4.x supports NodeJS versions 8 and higher.
Metalsmith 2.3.0 and below support NodeJS versions all the way back to 0.12.

Credits

Special thanks to Ian Storm Taylor, Andrew Meyer, Dominic Barnes, Andrew Goodricke, Ismay Wolff, Kevin Van Lierde and others for their contributions!

License

Changelog

[2.5.0] - 2022-06-10

Important note to metalsmith-watch users: Although 2.5.0 is a semver-minor release, it breaks compatibility with metalsmith-watch, which relies on the Metalsmith < 2.4.x private method signature using the outdated unyield package. See issue #374 for more details.

Added

• [#354] Added Metalsmith#env method. Supports passing DEBUG and DEBUG_LOG amongst others. Sets CLI: true when run from the metalsmith CLI. b42df8c, 446c676, 33d936b, 4c483a3
• [#356] Added Metalsmith#debug method for creating plugin debuggers
• [#362] Upgraded all generator-based methods (Metalsmith#read,Metalsmith#readFile,Metalsmith#write,Metalsmith#writeFile, Metalsmith#run and Metalsmith#process) to dual callback-/ promise-based methods 16a91c5, faf6ab6, 6cb6229
• Added org migration notification to postinstall script to encourage users to upgrade 3a11a24

Removed

• [#231] Dropped support for Node < 12 0a53007
• Dependencies:
  • thunkify: replaced with promise-based implementation faf6ab6
  • unyield replaced with promise-based implementation faf6ab6
  • co-fs-extra: replaced with native Node.js methods faf6ab6
  • chalk: not necessary for the few colors used by Metalsmith CLI 1dae1cb
  • clone: see [#247] a871af6

Updated

• Restructured and updated README.md 0da0c4d
• [#247] Calling Metalsmith#metadata no longer clones the object passed to it, overwriting the previous metadata, but merges it into existing metadata.

Fixed

• [#355] Proper path resolution for edge-cases using CLI, running metalsmith from outside or subfolder of metalsmith.directory()5d75539