# gulp-permalinks

> Gulp plugin for easily creating permalinks for vinyl files.

Latest version **0.1.1** (published 2017-02-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install gulp-permalinks
pnpm add gulp-permalinks
yarn add gulp-permalinks
bun add gulp-permalinks
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2017-02-16 |
| First published | 2017-02-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=4 |
| Dependencies | 3 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6 |
| Author | Brian Woodward |
| Maintainers | doowb, jonschlinkert |
| Keywords | gulp, gulp-permalinks, gulpplugin, permalinks |

## Links

- npm: https://www.npmjs.com/package/gulp-permalinks
- Repository: https://github.com/doowb/gulp-permalinks
- Issues: https://github.com/doowb/gulp-permalinks/issues
- npm.io page: https://npm.io/package/gulp-permalinks

## Dependencies (3)

- [through2](https://npm.io/package/through2.md) ^2.0.3
- [permalinks](https://npm.io/package/permalinks.md) ^1.0.1
- [extend-shallow](https://npm.io/package/extend-shallow.md) ^2.0.1

## Recent versions

- 0.1.1 (latest) — 2017-02-16
- 0.1.0 — 2017-02-15

## README

# gulp-permalinks [![NPM version](https://img.shields.io/npm/v/gulp-permalinks.svg?style=flat)](https://www.npmjs.com/package/gulp-permalinks) [![NPM monthly downloads](https://img.shields.io/npm/dm/gulp-permalinks.svg?style=flat)](https://npmjs.org/package/gulp-permalinks)  [![NPM total downloads](https://img.shields.io/npm/dt/gulp-permalinks.svg?style=flat)](https://npmjs.org/package/gulp-permalinks) [![Linux Build Status](https://img.shields.io/travis/doowb/gulp-permalinks.svg?style=flat&label=Travis)](https://travis-ci.org/doowb/gulp-permalinks) [![Windows Build Status](https://img.shields.io/appveyor/ci/doowb/gulp-permalinks.svg?style=flat&label=AppVeyor)](https://ci.appveyor.com/project/doowb/gulp-permalinks)

> Gulp plugin for easily creating permalinks for vinyl files.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save gulp-permalinks
```

## Usage

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

## API

**Params**

* `structure` **{String}**: permalink structure to use for each file. See [permalinks](https://github.com/jonschlinkert/permalinks) for more details.
* `options` **{Object}**: Additional options to pass to [permalinks](https://github.com/jonschlinkert/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](https://github.com/jonschlinkert/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](http://gulpjs.com) pipeline.

**Example**

```js
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`.

```js
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.

```js
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.

```js
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.

```js
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](../../issues/new).

Please read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards.

### Building docs

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

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

### Running tests

Install dev dependencies:

```sh
$ npm install && npm test
```

### Author

**Brian Woodward**

* [github/doowb](https://github.com/doowb)
* [twitter/doowb](https://twitter.com/doowb)

### License

Copyright © 2017, [Brian Woodward](https://github.com/doowb).
MIT

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.4.2, on February 16, 2017._

---
_Source: https://npm.io/package/gulp-permalinks · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
