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 vinyl
files. 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/**')
.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']
}));
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 totrue
, 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
MIT