gulp-nav

A gulp plugin to help build navigation or breadcrumb elements implicitly from our file structure. The goal is to be useful with e.g. Bootstrap .nav classes and your favorite templating system. (If you need templates, try Jade.) gulp-nav can handle Vinyl file objects with stream contents and with buffer contents.

Imagine we have some source files in a directory hierarchy:

  .
  ├── greek
  │   ├── alpha.jade
  │   ├── beta.jade
  │   ├── delta.jade
  │   └── gamma.jade
  ├── index.jade
  ├── latin
  │   ├── b.jade
  │   ├── c.jade
  │   ├── index.jade
  │   └── letter-a.jade
  ├── one.jade
  ├── three.jade
  └── two.jade

We know how to .pipe these through appropriate plugins and transforms, leaving us with a bunch of output pages in a similar directory hierarchy. What about links between those pages, however? We don't want to hardcode that stuff! While each file is piped through, an object stored as a property of the Vinyl file object, which stored object knows where other files are located and what they are called, could be really useful to template plugins. With that information, a template could be written to build navbars, breadcrumbs, or whatever we want on our generated page.

What would this look like? If we had this in our gulpfile...

var gulp = require('gulp'),
    data = require('gulp-data'),
    matter = require('jade-var-matter'),
    nav = require('gulp-nav'),
    jade = require('gulp-jade');

gulp.task('default', function() {
    return gulp.src('src/**/*.jade')
        // gulp-nav will use title or order properties if they are included
        // in file.data, but that is completely optional
        .pipe(data(function(file) {
            return matter(String(file.contents));
        }))
        .pipe(nav())
        .pipe(jade())
        .pipe(gulp.dest('dist'));
});

...and our template file had something like this...

  nav
    ul.nav.nav-tabs
      for sibling in nav.siblings
        li
          a(href=sibling.href)= sibling.title

...that would be enough to generate easy, maintainable navbars! This slightly more elaborate template file generates the nav for the demo site.

The nav object referenced above has the following properties:

property	description
title	Identifier for this resource.
href	Relative link to this resource. null for a directory without an index.
active	Is this resource the current one? true or false.
parent	nav object representing this resource's parent. null for the root resource.
children	Array of nav objects representing this resource's children. Empty when this resource isn't a directory.
siblings	Array of nav objects representing this resource's parent's children. Includes this resource.
root	nav object representing the ancestor of all streamed resources.
hasActiveDescendant	Is a child (or child of child, etc.) of this resource active?

If you want children and siblings to be in a particular order, just have an order property defined on each file object. order should be a number, small for the "first" resource and large for the "last" resource in the directory.

There are a bunch of options we can pass into the plugin (in an object), which are currently undocumented because they have sensible defaults and they might change. If you want to know all about the options then read the source.

One current default is to expose the nav data at both the nav and data.nav (the latter for use with the new "data API") properties of the file object, although either or both of these may be overridden via the targets option.

Thanks!

gulp-nav is by Jess Austin and is distributed under the terms of the MIT license. Any and all potential contributions of issues and pull requests are welcome!

Special thanks to Arlando Battle for windows compatibility!