hudozka/node_modules/gulp/docs/writing-a-plugin/readme-conventions.md

README conventions

Follow README conventions to increase your plugin readability and usability.

Writing a Gulp Plugin > 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
  2. Type
  3. Default value
  4. Description
  5. 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).

---

gulp-handlebars

Handlebars plugin for gulp 3

Usage

First, install gulp-handlebars as a development dependency:

npm install --save-dev gulp-handlebars

Then, add it to your gulpfile.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:

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().

---

Example: Overloaded API

The following is an example of a plugin that has an overloaded API (from gulp-csslint).

---

gulp-csslint

CSSLint plugin for gulp 3

Usage

First, install gulp-csslint as a development dependency:

npm install --save-dev gulp-csslint

Then, add it to your gulpfile.js:

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 for valid rule IDs.

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.

gulp.src('./client/css/*.css')
  .pipe(csslint('csslintrc.json'))
  .pipe(csslint.reporter());

Results

Adds the following properties to the file object:

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.

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));
});

---