• Home
  • blog
  • How to Create a Static Site with Metalsmith

How to Create a Static Site with Metalsmith

My previous posts discussed reasons why you should or should not consider a static site generator. In summary, a static site generator builds HTML-only page files from templates and raw data typically contained in Markdown files. It offers some of the benefits of a CMS without the hosting, performance and security overheads.

A static site may be appropriate for a range of projects, including:


  • A small website or personal blog. Sites with a few dozen pages, infrequent posts and one or two authors could be ideal.
  • Technical documentation such as a REST API.
  • Application prototypes requiring a series of web page views.
  • An eBook — Markdown files can be converted to PDF or other formats as well as HTML.

In essence, a static site generator is a build tool. You could use one for running tasks or project scaffolding like you could with Grunt or Gulp.

Why Metalsmith?

The undisputed static site champion is Jekyll—a Ruby project launched in 2008. You don’t necessarily require Ruby expertise to use Jekyll but it will help. Fortunately, there is a wide range of open source static site generators for most popular languages. JavaScript options include Hexo, Harp and Assemble. You could also use a build tool such as Gulp for simpler projects.

I choose Metalsmith for this tutorial because it:

  1. is not aimed at specific project types such as blogs
  2. supports a wide range of template and data format options
  3. is lightweight
  4. has few dependencies
  5. uses a modular structure
  6. offers a simple plug-in architecture, and
  7. is easy to get started.

A demonstration website has been built for this tutorial. It won’t win any design awards but it illustrates the basic concepts. The Metalsmith build code can be examined and installed from the GitHub repository. Alternatively, you can follow the instructions here and create your own basic site.

I have used Metalsmith a couple of times—please don’t presume this is the definitive way to build every static site!

Install Metalsmith

Ensure you have Node.js installed (for example using nvm) then create a new project directory, e.g. project and initialize your package.json file:

cd project && cd project
npm init -y

Now install Metalsmith and the assorted plugins we’ll use to build our site. These are:

npm install --save-dev metalsmith metalsmith-assets metalsmith-browser-sync metalsmith-collections metalsmith-feed metalsmith-html-minifier metalsmith-in-place metalsmith-layouts metalsmith-mapsite metalsmith-markdown metalsmith-permalinks metalsmith-publish metalsmith-word-count handlebars

Project Structure

We’ll use the following structure for source (src) and build (build) directories within the project.

You can create your example files as described below or copy them directly from the demonstration src directory.


Page Markdown files are contained in src/html. This can contain one level of sub-directories for each website section, i.e.

  • src/html/start — pages describing the project in a specific order
  • src/html/article — assorted articles in reverse chronological order
  • src/html/contact — a single contact page

Each directory contains a single file which is the default page for that section. Other pages can use any unique name.

The build process will transform these files into directory-based permalinks, e.g.

  • src/html/start/ becomes /start/index.html
  • src/html/start/ becomes /start/installation/index.html

Each Markdown file provides the content and meta information known as “front-matter” at the top between --- markers, e.g.

title: My page title
description: A description of this page.
layout: page.html
priority: 0.9
date: 2016-04-19
publish: draft

This is a demonstration page.

## Example title
Body text.

Continue reading %How to Create a Static Site with Metalsmith%