gulp-ssg

gulp-ssg

A gulp plugin to help generate a static website from a bunch of files.

Installation

$ npm install gulp-ssg

Usage

var ssg = require('gulp-ssg');

gulp.task('html', function() {
    return gulp.src('content/**/*.html')
        .pipe(ssg())
        .pipe(gulp.dest('public/'));
});

This will add properties to each file's data property:

• file.data.url - A URL, which is the file.relative with a slash prepended and any trailing index.* removed
• file.data.dirtyUrl - As above, but without trailing index.* removed
• file.data.root - A pointer to the root file
• file.data.parent - A pointer to the parent file
• file.data.children - An array of pointers to child files
• file.data.siblings - An array of pointers to sibling files

To explain these a bit more:

• The root file is the root index.html file. If there isn't one then root will be null.
• The parent file is the parent index.html file. If there isn't one then parent will be null.
• The children are all the files that have a URL that starts with the current files path plus at least one more token in there path. Because index.html is truncated from URLs this means /foo/bar/ and /foo/fred.html are both children of /foo/index.html.
• The siblings are all the files that have a common parent URL.

This plug-in follows the gulp-data convention of using file.data, so anything returned from a gulp-data pipe will be merged with the properties above.

Example

So how can this be used? It gets more interesting when combined with other pipes. For example:

var gulp = require('gulp');
var ssg = require('gulp-ssg');
var rename = require('gulp-rename');
var data = require('gulp-data');
var matter = require('gray-matter');
var markdown = require('gulp-markdown');
var wrap = require('gulp-wrap');
var del = require('del');

gulp.task('default', function() {

    return gulp.src('src/content/*.md')

        // Extract YAML front-matter and assign with gulp-data
        .pipe(data(function(file) {
            var m = matter(String(file.contents));
            file.contents = new Buffer(m.content);
            return m.data;
        }))

        // markdown -> HTML
        .pipe(markdown())

        // Rename to .html
        .pipe(rename({ extname: '.html' }))

        // Run through gulp-ssg
        .pipe(ssg())

        // Wrap file in template
        .pipe(wrap(
          { src: 'src/templates/template.html' },
          { siteTitle: 'Example Website'},
          { engine: 'hogan' }
        ))

        // Output to build directory
        .pipe(gulp.dest('public/'));
});

There are complete examples with templates in the git repo.

Options

baseUrl string

The base URL of the site, defaults to '/'. This should be the path to where your site will eventually be deployed.

sort string

A property to sort pages by, defaults to url. For example, this could be a property like order extracted from the YAML front-matter.