Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

gulp-ssg NPM version 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.


No description, website, or topics provided.


You can’t perform that action at this time.