How to Create a Static Site with Metalsmith

Category: HTML & CSS, jamesh, JavaScript, jekyll, Metalsmith, node, node.js, static site, static site generator, Tools & Libraries

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:

[author_more]

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:

is not aimed at specific project types such as blogs
supports a wide range of template and data format options
is lightweight
has few dependencies
uses a modular structure
offers a simple plug-in architecture, and
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:

metalsmith-assets — includes static assets in your Metalsmith build
metalsmith-browser-sync — incorporates BrowserSync into your workflow
metalsmith-collections — adds collections of files to the global metadata
metalsmith-feed — generates an RSS feed for a collection
metalsmith-html-minifier — minifies HTML files using kangax/html-minifier
metalsmith-in-place — renders templating syntax in source files
metalsmith-layouts — applies layouts to your source files
metalsmith-mapsite — generates a sitemap.xml file
metalsmith-markdown — converts markdown files
metalsmith-permalinks — applies a custom permalink pattern to files
metalsmith-publish — adds support for draft, private, and future-dated posts
metalsmith-word-count — computes word count / average reading time of all paragraphs in a HTML file

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.

Pages

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 index.md 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/index.md becomes /start/index.html
src/html/start/installation.md 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%

blog