A starter template for Metalsmith + Gulp + Jest projects

metalsmith-gulp-boilerplate Build Status

A starter template for Metalsmith + Gulp + Jest projects.


  1. Make your project folder and clone metalsmith-boilerplate into it
   $ mkdir new-metalsmith-project
   $ git clone new-metalsmith-project
  1. Run the following command within your new project directory:
   $ npm install
  1. Assuming you have installed Gulp globally, start the build/watch process with this command:
   $ gulp
  1. If this is your first build, you might want to package your javascript dependencies with this command:
   $ gulp build-deps

This will gather all the js files in your js/vendor/ directory and package them into js/bin/dependencies.min.js. Use this command each time you add a new dependency to js/vendor.

  1. Now you are ready to start Metalsmithing! :thumbsup:

Usage Notes


This boilerplate represents an opinionated setup for building static websites with Metalsmith and Gulp. It assumes you want to use Browserify with your custom scripts and helps you wrap all your javascript dependencies into one file. It uses the Sass precomplier and Handlebars templates. Gulp is responsible for the live-reloading (via BrowserSync) and the CSS / Browserify steps. Metalsmith is responsible for compiling/generating the site files.


Use the site.json file to change or update the default configuration settings. The current defaults contain your source path, destination path, filenames to assign generated files, globs for gulp, and general site metadata. If you want to change the gulp or metalsmith builds, use the gulpfile.js or metalsmith.js files.

Packaging Javascript Dependencies

When you have added new dependencies to your js/vendor directory, package the dependencies with this command:

$ gulp build-deps

By default, this will concatenate and minify all your dependencies to this file: js/bin/dependencies.min.js, but you can override the file name and location in the sites.json file. If you do not use this command, then you will need to import your dependencies into your templates manually. This build step is not automatic, because it is unnecessary to bundle your dependencies on every gulp/metalsmith build if your dependencies only change rarely.

Importing Files into Your Templates

By default, your generated files are available in Handlebars like so:

<!-- your generated css -->
<link rel="stylesheet" href="{{rootPath}}css/styles.min.css">

<!-- your generated js dependencies -->
<script src="{{rootPath}}js/bin/dependencies.min.js"></script>

<!-- your browserified scripts -->
<script src="{{rootPath}}js/bin/bundle.min.js"></script>

Features and Defaults

These are the current defaults, but you can swap these out for anything you want.

  • Templating: Handlebars via metalsmith-layouts
  • Easy Template Helper Integration: Any node modules dropped into layouts/helpers will automatically be available to your Handlebars templates
  • CSS Precompiler: SASS
  • Live Reloading: BrowserSync
  • Relative Navigation: Solved with metalsmith-rootpath
  • Browserify: Browserify your javascript source automatically
  • Dependency Wrapping: Minify and concat all your dependencies into one file
  • Unit Testing: via Jest

What Next?



To the extent possible under law, Michael Wuergler has waived all copyright and related or neighboring rights to this work.

Related Repositories



A starter template for Metalsmith + Gulp + Jest projects ...



Static Site Boilerplate using Metalsmith & Gulp ...