
Metalsmith is a plugin-based static site generator originally from Segment . It's a current favorite of mine because of how sites are built as a pipeline of plugins where the output of each plugin is the input of the next. This allows for strong control over what happens and when it happens.
A simple pipeline could look like:
- Set the input directory.
- Convert all Markdown files to HTML.
- Process all HTML files through a Handlebars template.
- Set the output directory.
- Clean the output directory.
- Output all files.
While a more complex pipeline could look like:
- Set the input directory.
- Validate the frontmatter in all Markdown files.
- Compile all Sass files to CSS.
- Reduce the size of large images.
- Convert all Markdown files to HTML.
- Process all HTML files through a Handlebars template.
- Add a favicon.
- Minify HTML, CSS, and JavaScript.
- Build a sitemap.
- Set the output directory.
- Clean the output directory.
- Output all files.
As of writing, this website is built using Metalsmith and 44 plugins.
In this tutorial we'll first set up a blank project and then we'll continue to iterate on it by adding additional plugins and source files.
Setting up Metalsmith
Setting up a Metalsmith project is a lot like setting up any other Node.js project, in the end you'll have a package.json and package-lock.json, index.js, and other source files throughout.
This guide assumes you already have Node.js installed.
1. Directory structure
The official Metalsmith examples recommend a certain directory structure, so we'll stick to that. Throughout this guide I will continue to list the directory tree to keep things clear.
Go ahead and make a new directory for your project and a src/ directory under that:
1.
2└── src
2. Set up nvm
nvm or "Node Version Manager" is a way to install and run different versions of Node.js at the same time on one machine. But more importantly, it lets the project indicate what version should be used.
The full instructions for installation are on GitHub , but in general it is as simple as:
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bashMetalsmith requires a Node.js version above 0.12.x so we'll instruct nvm to use the latest LTS version (currently 10.16.3) by creating a .nvmrc file at the root of our project with the contents:
1lts/*
And then running the command:
$ nvm installNow our directory tree will look like:
1.
2├── .nvmrc
3└── src
3. Set up npm
npm or "Node Package Manager" is a tool to install Node.js packages and is the recommended way to install Metalsmith. To set up our project run the command:
$ npm initAnd follow the prompts. Hitting the enter key for all prompts is fine for now if you don't want to fill it all out. This will create an initialized package.json for us:
1.
2├── .nvmrc
3├── package.json
4└── src
4. Set up Metalsmith
From the root of our project run the command:
$ npm install --save metalsmithWhich will install Metalsmith and all required dependencies. This will create the node_modules/ directory (with many subdirectories in it) and the package-lock.json file. To save some space I'll skip writing out all the extra node_modules/ subdirectories:
1.
2├── .nvmrc
3├── node_modules
4│ └── metalsmith
5├── package-lock.json
6├── package.json
7└── src
Now we're going to set up a dummy pipeline to make sure Metalsmith is installed and working right. Create an index.js file with the contents:
1const Metalsmith = require('metalsmith');
2
3Metalsmith(__dirname)
4 .source('./src') // source directory for the pipeline
5 .destination('./build') // destination directory of the pipeline
6 .clean(true) // clean the destination directory before build
7 .build(function (err) { // execute the build
8 if (err) {
9 throw err;
10 }
11 });
And then run the command:
$ node indexIf there is no output from the command we know Metalsmith is working right.
5. Adding an index page
You might have noticed after the node index command above it didn't actually create the build/ directory like we configured in index.js, that's because there's nothing for it to output yet. Let's fix that by creating a file src/index.html with the contents:
1<!DOCTYPE html>
2<html lang="en">
3<head>
4 <meta charset="UTF-8">
5 <title></title>
6</head>
7<body>
8</body>
9</html>
And then try the command again:
$ node indexWe'll know this worked if it copied src/index.html to build/index.html:
1.
2├── .nvmrc
3├── build
4│ └── index.html
5├── index.js
6├── node_modules
7│ └── metalsmith
8├── package-lock.json
9├── package.json
10└── src
11 └── index.html
6. Creating a layout
We're not living in 1999 anymore and we have the power of HTML templating systems these days, thankfully. Handlebars (.hbs) is a popular choice for Metalsmith and is what we're going to use, but there are plugins for other systems such as Nunjucks (.njk) as well.
Let's install both the layouts plugin as well as Handlebars like we did with Metalsmith:
$ npm install --save metalsmith-layouts jstransformer-handlebarsNow we need to add metalsmith-layouts as a step in our build process in index.js:
1const Metalsmith = require('metalsmith');
2const layouts = require('metalsmith-layouts');
3
4Metalsmith(__dirname)
5 .source('./src') // source directory for the pipeline
6 .use(layouts({ // <-- process all HTML files with Handlebars
7 default: 'page.hbs',
8 engine: 'handlebars'
9 }))
10 .destination('./build') // destination directory of the pipeline
11 .clean(true) // clean the destination directory before build
12 .build(function (err) { // execute the build
13 if (err) {
14 throw err;
15 }
16 });
By default metalsmith-layouts will look for templates in the layouts/ directory, so let's create that and a file layouts/page.hbs that looks very similar to src/index.html but with a special Handlebars expression:
1<html lang="en">
2<head>
3 <meta charset="UTF-8">
4 <title></title>
5</head>
6<body>
7{{{ contents }}}
8</body>
9</html>
{{{ contents }}} here will be replaced with the body of any source file that uses this template. We use {{{ }}} instead of {{ }} to preserve any HTML in the source files.
Now that we've moved the structural HTML from src/index.html to layouts/page.hbs we can write a page body in src/index.html:
1<h1>This is a title!</h1>
2<p>This is a paragraph.</p>
Then build:
$ node indexWe'll end up with build/index.html looking like:
1<html lang="en">
2<head>
3 <meta charset="UTF-8">
4 <title></title>
5</head>
6<body>
7<h1>This is a title!</h1>
8<p>This is a paragraph.</p>
9</body>
10</html>
And a directory tree looking like:
1.
2├── .nvmrc
3├── build
4│ └── index.html
5├── index.js
6├── layouts
7│ └── page.hbs
8├── node_modules
9│ ├── jstransformer-handlebars
10│ ├── metalsmith
11│ └── metalsmith-layouts
12├── package-lock.json
13├── package.json
14└── src
15 └── index.html
7. Using Markdown
It's more common to use Markdown instead of HTML as an input source in Metalsmith because of its ease-of-use and familiarity among developers. Plus it's more portable so you'll be able to use it with a different static site generator in the future.
Markdown conversion requires another plugin:
$ npm install --save metalsmith-markdownAnd an addition to our index.js:
1const Metalsmith = require('metalsmith');
2const markdown = require('metalsmith-markdown');
3const layouts = require('metalsmith-layouts');
4
5Metalsmith(__dirname)
6 .source('./src') // source directory for the pipeline
7 .use(markdown()) // <-- convert Markdown to HTML
8 .use(layouts({ // process all HTML files with Handlebars
9 default: 'page.hbs',
10 engine: 'handlebars'
11 }))
12 .destination('./build') // destination directory of the pipeline
13 .clean(true) // clean the destination directory before build
14 .build(function (err) { // execute the build
15 if (err) {
16 throw err;
17 }
18 });
Then rename src/index.html to src/index.md and change it to Markdown syntax:
1# This is a title!
2
3This is a paragraph.
And build:
$ node indexWhich will give us a build/index.html very similar to before (heading IDs can be turned off with a metalsmith-markdown option):
1<html lang="en">
2<head>
3 <meta charset="UTF-8">
4 <title></title>
5</head>
6<body>
7<h1 id="this-is-a-header">This is a title!</h1>
8<p>This is a paragraph.</p>
9</body>
10</html>
And a directory tree:
1.
2├── .nvmrc
3├── build
4│ └── index.html
5├── index.js
6├── layouts
7│ └── page.hbs
8├── node_modules
9│ ├── jstransformer-handlebars
10│ ├── metalsmith
11│ ├── metalsmith-layouts
12│ └── metalsmith-markdown
13├── package-lock.json
14├── package.json
15└── src
16 └── index.html
8. Frontmatter in Markdown
Wouldn't it be neat if we had a real page title instead of <title></title>? That's where frontmatter and page metadata comes in.
According to Middleman :
Frontmatter allows page-specific variables to be included at the top of a template using the YAML or JSON format.
Adding frontmatter to our src/index.md looks like this:
1---
2
3title: This is the Index
4
5---
6
7# This is a title!
8
9This is a paragraph.
Where anything between the ---'s is parsed as YAML and is made available to the templating system. Now we can use that information in layouts/page.hbs like so:
1<html lang="en">
2<head>
3 <meta charset="UTF-8">
4 <title>{{ title }}</title>
5</head>
6<body>
7{{{ contents }}}
8</body>
9</html>
And after building:
$ node indexWe get build/index.html:
1<html lang="en">
2<head>
3 <meta charset="UTF-8">
4 <title>This is the Index</title>
5</head>
6<body>
7<h1 id="this-is-a-header">This is a title!</h1>
8<p>This is a paragraph.</p>
9</body>
10</html>
9. Adding another page
All of the work so far has set us up nicely to be able to add new, consistent pages very quickly. Let's add an about page at src/about.md:
1---
2
3title: About
4
5---
6
7This is a sample website built with Metalsmith.
Which after build:
$ node indexProduces build/help.html:
1<html lang="en">
2<head>
3 <meta charset="UTF-8">
4 <title>About</title>
5</head>
6<body>
7<p>This is a sample website built with Metalsmith.</p>
8</body>
9</html>
And a directory tree looking like:
1.
2├── .nvmrc
3├── build
4│ ├── help.html
5│ └── index.html
6├── index.js
7├── layouts
8│ └── page.hbs
9├── node_modules
10│ ├── jstransformer-handlebars
11│ ├── metalsmith
12│ ├── metalsmith-layouts
13│ └── metalsmith-markdown
14├── package-lock.json
15├── package.json
16└── src
17 ├── help.md
18 └── index.html
10. Using template partials
Good development practices encourage splitting up code into smaller pieces that can be composed together. Template partials allow us to define HTML snippets, such as headers or footers, that can be used and re-used in our templates.
To make our lives easier let's install another plugin:
$ npm install --save metalsmith-discover-partialsAnd add it to our index.js:
1const Metalsmith = require('metalsmith');
2const discoverPartials = require('metalsmith-discover-partials');
3const markdown = require('metalsmith-markdown');
4const layouts = require('metalsmith-layouts');
5
6Metalsmith(__dirname)
7 .source('./src') // source directory for the pipeline
8 .use(discoverPartials()) // <-- find and register template partials
9 .use(markdown()) // convert Markdown to HTML
10 .use(layouts({ // process all HTML files with Handlebars
11 default: 'page.hbs',
12 engine: 'handlebars'
13 }))
14 .destination('./build') // destination directory of the pipeline
15 .clean(true) // clean the destination directory before build
16 .build(function (err) { // execute the build
17 if (err) {
18 throw err;
19 }
20 });
metalsmith-discover-partials looks for Handlebars files in the partials/ directory by default, so go ahead and create that and the file partials/header.hbs:
1<b>This is the header.</b>
2<hr>
And we can reference it by its filename base in layouts/page.hbs like this:
1<html lang="en">
2<head>
3 <meta charset="UTF-8">
4 <title>{{ title }}</title>
5</head>
6<body>
7{{>header}}
8{{{ contents }}}
9</body>
10</html>
And after one last build:
$ node indexWe end up with a build/index.html of:
1<html lang="en">
2<head>
3 <meta charset="UTF-8">
4 <title>This is the Index</title>
5</head>
6<body>
7<b>This is the header</b>
8<hr>
9<h1 id="this-is-a-title">This is a title!</h1>
10<p>This is a paragraph.</p>
11</body>
12</html>
And a directory tree of:
1.
2├── .nvmrc
3├── build
4│ ├── help.html
5│ └── index.html
6├── index.js
7├── layouts
8│ └── page.hbs
9├── node_modules
10│ ├── jstransformer-handlebars
11│ ├── metalsmith
12│ ├── metalsmith-discover-partials
13│ ├── metalsmith-layouts
14│ └── metalsmith-markdown
15├── package-lock.json
16├── package.json
17├── partials
18│ └── header.hbs
19└── src
20 ├── help.md
21 └── index.html
Conclusion
Metalsmith is a great option for someone looking for a lot of control in a static site generator. There are many different plugins that exist for processing different kinds of inputs and there is no strict order they need to be used in. With a minimal amount of setup that should be familiar to existing Node.js developers it's very quick to get started with Metalsmith.


