gulp-metalsmith

API changes!

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

Tutorial

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

About

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.

Installation

$ npm install --save-dev gulp-metalsmith

Usage

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/**')
    .pipe(metalsmith())
    .pipe(gulp.dest('build'));
});

All options:

const gulp = require('gulp');
const metalsmith = require('gulp-metalsmith');
 
gulp.src('src/**').pipe(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: [
    markdown(),
    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:

gulp.src('src/**').pipe(metalsmith({
  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"

Author

Jakub Elżbieciak / @jelzbieciak

License

MIT