node package manager


gulp-ssg NPM version Dependency Status Build Status

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


$ npm install gulp-ssg


var ssg = require('gulp-ssg');
gulp.task('html', function() {
    return gulp.src('content/**/*.html')

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

  • - A URL, which is the file.relative with a slash prepended and any trailing index.* removed
  • - As above, but without trailing index.* removed
  • - A pointer to the root file
  • - A pointer to the parent file
  • - An array of pointers to child files
  • - 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, so anything returned from a gulp-data pipe will be merged with the properties above.


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);
        // markdown -> HTML 
        // Rename to .html 
        .pipe(rename({ extname: '.html' }))
        // Run through gulp-ssg 
        // Wrap file in template 
          { src: 'src/templates/template.html' },
          { siteTitle: 'Example Website'},
          { engine: 'hogan' }
        // Output to build directory 

There are complete examples with templates in the git repo.


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.