Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including gulp-metalsmith with all npm packages installed. Try it out:

var gulpMetalsmith = require("gulp-metalsmith")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

gulp-metalsmith v1.1.0

Lightweight gulp plugin for Metalsmith


npm Build Status Code Coverage npm Dependency Status devDependency Status

API changes!

Please note that as of v1.0.0 metalsmith.json() method is not available. Use the json configuration option instead.


This README file doesn't make sense at first glance or is too technical? See the gulp-metalsmith tutorial!


gulp-metalsmith is a gulp plugin that incorporates Metalsmith builds into gulp pipelines. It aims to be as lightweight as possible. It is shipped with an API-compatible Metalsmith replacement that can reuse Metalsmith plugins. It can be fed with JSON files containing page definitions.

After build gulp-metalsmith streams out vinylfiles. The main difference between the bundled Metalsmith and the normal Metalsmith is that it does not perform any disc read/write operations, leaving it to gulp.


$ npm install --save-dev gulp-metalsmith


The simplest build task (just copies all files from src/ to build/):

const gulp = require('gulp');
const metalsmith = require('gulp-metalsmith');

gulp.task('metalsmith', function() {
  return gulp.src('src/**')

All options:

const gulp = require('gulp');
const metalsmith = require('gulp-metalsmith');

  // Metalsmith's root directory, for example for locating templates, defaults to CWD
  root: __dirname,
  // Files to exclude from the build
  ignore: ['src/*.tmp'],
  // Parsing frontmatter, defaults to true
  frontmatter: true,
  // Metalsmith plugins to use:
  use: [
    layouts({engine: 'swig'})
  // Initial Metalsmith metadata, defaults to {}
  metadata: {
    site_title: 'Sample static site'
  // List of JSON files that contain page definitions
  // true means "all JSON files", see the section below
  json: ['src/pages.json']

Use it with JSON

Given the file src/pages.json:

  "index.html": {
    "title": "Homepage",
    "layout": "basic.swig",
    "contents": "<p>In euismod eleifend nunc ac pretium...</p>"
  "contact.html": {
    "title": "Contact",
    "layout": "basic.swig",
    "contents": "<p>Lorem ipsum dolor sit amet...</p>"

You can do this:

  use: [layouts({engine: 'swig'})],
  json: true

This way your Metalsmith build will contain two additional files, index.html and contact.html. The source file pages.json won't be included. Following rules apply:

  • be default all JSON files in the pipeline are included "as is"
  • when the json configuration options is set to true, all JSON files are parsed and replaced with files defined in their content
  • when the json configuration option is a glob string or an array of globs, only JSON files matching these globs are parsed and define new files. The rest of JSON files is passed "as is"


Jakub Elżbieciak / @jelzbieciak




RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free