https://github.com/doowb/gulp-permalinks
Gulp plugin for easily creating permalinks for vinyl files.
https://github.com/doowb/gulp-permalinks
Last synced: about 1 year ago
JSON representation
Gulp plugin for easily creating permalinks for vinyl files.
- Host: GitHub
- URL: https://github.com/doowb/gulp-permalinks
- Owner: doowb
- License: mit
- Created: 2017-02-15T19:28:25.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2017-02-16T21:59:13.000Z (over 9 years ago)
- Last Synced: 2025-05-09T02:14:39.637Z (about 1 year ago)
- Language: JavaScript
- Homepage: https://github.com/doowb/gulp-permalinks
- Size: 16.6 KB
- Stars: 6
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/contributing.md
- License: LICENSE
Awesome Lists containing this project
README
# gulp-permalinks [](https://www.npmjs.com/package/gulp-permalinks) [](https://npmjs.org/package/gulp-permalinks) [](https://npmjs.org/package/gulp-permalinks) [](https://travis-ci.org/doowb/gulp-permalinks) [](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._