gulp-permalinks

Gulp plugin for easily creating permalinks for vinyl files.

Install

Install with npm:

$ npm install --save gulp-permalinks

Usage

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

API

Params

• structure {String}: permalink structure to use for each file. See permalinks for more details.
• options {Object}: Additional options to pass to permalinks and to control how files are handled in the stream.
• options.flush {Boolean}: When set to true the files will be pushed back onto the stream in the "flush" function to ensure that all files are updated before continuing. Defaults to false.
• options.update {Boolean}: When set to false the files' path property will not be updated with the new permalink. Defaults to true.
• options.permalinks {Object}: Optionally pass your own instance of permalinks.
• fn {Function}: Optional function that will be passed the file as it comes through the stream. This allows a user to set custom properties on file.data to be available in the structure.
• returns {Stream}: Stream that can be used in a gulp pipeline.

Example

gulp.task('permalinks', function() {
  return gulp.src('path/to/posts/*.md')
    .pipe(permalinks('blog/:stem/index.html'))
    .pipe(gulp.dest('_gh_pages'));
});

Examples

Default file properties

This example uses somes of the default file properties calculated from the file.path.

gulp.task('permalinks', function() {
  return gulp.src('path/to/posts/*.md')
    .pipe(permalinks('blog/:stem/index.html'))
    .pipe(gulp.dest('_gh_pages'));
});

// writes to '_gh_pages/blog/my-file-stem/index.html'

Custom helpers

This example registers some custom helpers by passing them into the plugin through the options object.

gulp.task('permalinks', function() {
  var options = {
    helpers: {
      foo: function() {
        return this.context.stem.toUpperCase();
      },
      date: function() {
        return moment().format('YYYY/MM/DD');
      }
    }
  }

  return gulp.src('path/to/posts/*.md')
    .pipe(permalinks('blog/:date/:foo.html', options))
    .pipe(gulp.dest('_gh_pages'));
});

// writes to '_gh_pages/blog/2017/02/15/MY-FILE-STEM.html'

Custom presets

This example registers some custom presets by passing them into the plugin through the options object.

gulp.task('permalinks', function() {
  var options = {
    presets: {
      blog: 'blog/:stem/index.html'
    }
  };

  return gulp.src('path/to/posts/*.md')
    .pipe(permalinks('blog', options))
    .pipe(gulp.dest('_gh_pages'));
});

// writes to '_gh_pages/blog/my-file-stem/index.html'

Custom data

This example registers some custom data by passing it into the plugin through the options object.

gulp.task('permalinks', function() {
  var options = {
    data: {
      foo: 'bar',
      baz: 'qux'
    }
  };

  return gulp.src('path/to/posts/*.md')
    .pipe(permalinks('blog/:foo/:baz/:stem/index.html', options))
    .pipe(gulp.dest('_gh_pages'));
});

// writes to '_gh_pages/blog/bar/qux/my-file-stem/index.html'

About

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Please read the contributing guide for advice on opening issues, pull requests, and coding standards.

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Running tests

Install dev dependencies:

$ npm install && npm test

Author

Brian Woodward

• github/doowb
• twitter/doowb

License

Copyright © 2017, Brian Woodward. MIT

This file was generated by verb-generate-readme, v0.4.2, on February 16, 2017.