219 lines
6.5 KiB
Markdown
219 lines
6.5 KiB
Markdown
# README conventions
|
|
|
|
> Follow README conventions to increase your plugin readability and usability.
|
|
|
|
[Writing a Gulp Plugin](README.md) > README conventions
|
|
|
|
A plugin README should have the following parts at a minimum:
|
|
|
|
1. **Heading**: Give a short introduction to your plugin
|
|
* Include the version of gulp your plugin was designed for
|
|
* Include any badges on the same line as the heading
|
|
1. **Usage**: Include a simple usage example
|
|
* Show the plugin used on the context of a `gulpfile.js`
|
|
* Cover the most common or simplest use case
|
|
1. **API**: Document your plugin's API
|
|
* For individual parameters, include:
|
|
1. Parameter name
|
|
1. Type
|
|
1. Default value
|
|
1. Description
|
|
1. Optional example for complex options
|
|
* If a parameter accepts an Object, do the above for each property
|
|
* If your plugin accepts overloaded arguments, document each style individually
|
|
|
|
|
|
# Example: Options object
|
|
|
|
The following is an example of a plugin that takes a single options object (from [gulp-handlebars](https://github.com/lazd/gulp-handlebars)).
|
|
|
|
|
|
***
|
|
|
|
# gulp-handlebars [![NPM version][handlebars-npm-image]][handlebars-npm-url] [![Build status][handlebars-travis-image]][handlebars-travis-url]
|
|
> Handlebars plugin for gulp 3
|
|
|
|
## Usage
|
|
|
|
First, install `gulp-handlebars` as a development dependency:
|
|
|
|
```shell
|
|
npm install --save-dev gulp-handlebars
|
|
```
|
|
|
|
Then, add it to your `gulpfile.js`:
|
|
|
|
```js
|
|
var handlebars = require('gulp-handlebars');
|
|
|
|
gulp.task('templates', function(){
|
|
gulp.src(['client/templates/*.hbs'])
|
|
.pipe(handlebars({
|
|
namespace: 'MyApp.templates',
|
|
outputType: 'hybrid'
|
|
}))
|
|
.pipe(concat('templates.js'))
|
|
.pipe(gulp.dest('build/js/'));
|
|
});
|
|
```
|
|
|
|
## API
|
|
|
|
### handlebars(options)
|
|
|
|
#### options.namespace
|
|
Type: `String`
|
|
Default: `templates`
|
|
|
|
The namespace in which the precompiled templates will be assigned. Use dot notation (e.g. `App.Templates`) for nested namespaces or false to declare templates in the global namespace.
|
|
|
|
#### options.outputType
|
|
Type: `String`
|
|
Default: `browser`
|
|
|
|
The desired output type. One of the following:
|
|
|
|
* `browser` - Produce plain JavaScript files for the browser
|
|
* `hybrid` - Produce Node modules that can optionally be used on the frontend
|
|
* `node` - Produce Node modules
|
|
* `amd` - Produce AMD modules
|
|
* `commonjs` - Produce CommonJS modules
|
|
* `bare` - Return an unmolested function definition
|
|
|
|
#### options.declareNamespace
|
|
Type: `Boolean`
|
|
Default: `true`
|
|
|
|
If true, non-destructively declare all parts of the namespace. This option is only necessary when `options.type` is `browser` or `hybrid`.
|
|
|
|
For example, if the namespace is `MyApp.Templates` and a template is named `App.Header.hbs`, the following declaration will be present in the output file for that template:
|
|
|
|
```js
|
|
this["MyApp"] = this["MyApp"] || {};
|
|
this["MyApp"]["templates"] = this["MyApp"]["templates"] || {};
|
|
this["MyApp"]["templates"]["App"] = this["MyApp"]["templates"]["App"] || {};
|
|
this["MyApp"]["templates"]["App"]["Header"] = function () {};
|
|
```
|
|
|
|
When processing multiple templates under a given namespace, this will result in duplicate declarations. That is, the non-destructive declaration of the namespace will be repeated for each template compiled.
|
|
|
|
#### options.processName
|
|
Type: `Function`
|
|
Default: Strip file extension
|
|
|
|
This option accepts a function which takes one argument (the template filepath) and returns a string which will be used as the key for the precompiled template object. By default, the filename minus the extension is used.
|
|
|
|
If this function returns a string containing periods (not including the file extension), they will be represented as a sub-namespace. See `options.declareNamespace` for an example of the effect.
|
|
|
|
#### options.compilerOptions
|
|
Type: `Object`
|
|
|
|
Compiler options to pass to `Handlebars.precompile()`.
|
|
|
|
|
|
[handlebars-travis-url]: http://travis-ci.org/lazd/gulp-handlebars
|
|
[handlebars-travis-image]: https://secure.travis-ci.org/lazd/gulp-handlebars.png?branch=master
|
|
[handlebars-npm-url]: https://npmjs.org/package/gulp-handlebars
|
|
[handlebars-npm-image]: https://badge.fury.io/js/gulp-handlebars.png
|
|
***
|
|
|
|
|
|
# Example: Overloaded API
|
|
|
|
The following is an example of a plugin that has an overloaded API (from [gulp-csslint](https://github.com/lazd/gulp-csslint)).
|
|
|
|
|
|
***
|
|
# gulp-csslint [![NPM version][csslint-npm-image]][csslint-npm-url] [![Build status][csslint-travis-image]][csslint-travis-url]
|
|
> CSSLint plugin for gulp 3
|
|
|
|
## Usage
|
|
|
|
First, install `gulp-csslint` as a development dependency:
|
|
|
|
```shell
|
|
npm install --save-dev gulp-csslint
|
|
```
|
|
|
|
Then, add it to your `gulpfile.js`:
|
|
|
|
```javascript
|
|
var csslint = require('gulp-csslint');
|
|
|
|
gulp.task('css', function() {
|
|
gulp.src('./client/css/*.css')
|
|
.pipe(csslint())
|
|
.pipe(csslint.reporter());
|
|
});
|
|
```
|
|
|
|
## API
|
|
|
|
### csslint(ruleConfiguration)
|
|
|
|
#### ruleConfiguration
|
|
Type: `Object`
|
|
|
|
You can pass rule configuration as an object. See the [list of rules by ID on the CSSLint wiki](https://github.com/stubbornella/csslint/wiki/Rules-by-ID) for valid rule IDs.
|
|
|
|
```javascript
|
|
gulp.src('./client/css/*.css')
|
|
.pipe(csslint({
|
|
'shorthand': false
|
|
}))
|
|
.pipe(csslint.reporter());
|
|
```
|
|
|
|
### csslint(csslintrc)
|
|
|
|
#### csslintrc
|
|
Type: `String`
|
|
|
|
You can also pass the path to your csslintrc file instead of a rule configuration object.
|
|
|
|
```javascript
|
|
gulp.src('./client/css/*.css')
|
|
.pipe(csslint('csslintrc.json'))
|
|
.pipe(csslint.reporter());
|
|
```
|
|
|
|
## Results
|
|
|
|
Adds the following properties to the file object:
|
|
|
|
```javascript
|
|
file.csslint.success = true; // or false
|
|
file.csslint.errorCount = 0; // number of errors returned by CSSLint
|
|
file.csslint.results = []; // CSSLint errors
|
|
file.csslint.opt = {}; // The options you passed to CSSLint
|
|
```
|
|
|
|
## Custom Reporters
|
|
|
|
Custom reporter functions can be passed as `cssline.reporter(reporterFunc)`. The reporter function will be called for each linted file and passed the file object as described above.
|
|
|
|
```javascript
|
|
var csslint = require('gulp-csslint');
|
|
var gutil = require('gulp-util');
|
|
|
|
var customReporter = function(file) {
|
|
gutil.log(gutil.colors.cyan(file.csslint.errorCount)+' errors in '+gutil.colors.magenta(file.path));
|
|
|
|
file.csslint.results.forEach(function(result) {
|
|
gutil.log(result.error.message+' on line '+result.error.line);
|
|
});
|
|
};
|
|
|
|
gulp.task('lint', function() {
|
|
gulp.files('./lib/*.js')
|
|
.pipe(csslint())
|
|
.pipe(csslint.reporter(customReporter));
|
|
});
|
|
```
|
|
|
|
[csslint-travis-url]: http://travis-ci.org/lazd/gulp-csslint
|
|
[csslint-travis-image]: https://secure.travis-ci.org/lazd/gulp-csslint.png?branch=master
|
|
[csslint-npm-url]: https://npmjs.org/package/gulp-csslint
|
|
[csslint-npm-image]: https://badge.fury.io/js/gulp-csslint.png
|
|
***
|