Move docs to repo

docs/FAQ.md

@@ -0,0 +1,50 @@
+# FAQ
+
+## Why gulp? Why not ____?
+
+See the [gulp introduction slideshow] for a rundown on how gulp came to be.
+
+## Is it "gulp" or "Gulp"?
+
+gulp is always lowercase.
+
+## Where can I find a list of gulp plugins?
+
+gulp plugins always include the `gulpplugin` keyword. [Search gulp plugins][search-gulp-plugins] or [view all plugins][npm plugin search].
+
+## I want to write a gulp plugin, how do I get started?
+
+See the [Writing a gulp plugin] wiki page for guidelines and an example to get you started.
+
+## My plugin does ____, is it doing too much?
+
+Probably. Ask yourself:
+
+1. Is my plugin doing something that other plugins may need to do?
+  - If so, that piece of functionality should be a separate plugin. [Check if it already exists on npm][npm plugin search].
+1. Is my plugin doing two, completely different things based on a configuration option?
+  - If so, it may serve the community better to release it as two separate plugins
+  - If the two tasks are different, but very closely related, it's probably OK
+
+## How should newlines be represented in plugin output?
+
+Always use gulp-util.newline (which is \n) to prevent diff issues between operating systems.
+
+## Where can I get updates on gulp?
+
+gulp updates can be found on the following twitters:
+
+- [@wearefractal](https://twitter.com/wearefractal)
+- [@eschoff](https://twitter.com/eschoff)
+- [@funkytek](https://twitter.com/funkytek)
+- [@gulpjs](https://twitter.com/gulpjs)
+
+## Does gulp have an IRC channel?
+
+Yes, come chat with us in #gulpjs on [Freenode].
+
+[Writing a gulp plugin]: writing-a-plugin/README.md
+[gulp introduction slideshow]: http://slid.es/contra/gulp
+[Freenode]: http://freenode.net/
+[search-gulp-plugins]: http://gratimax.github.io/search-gulp-plugins/
+[npm plugin search]: https://npmjs.org/browse/keyword/gulpplugin

docs/README.md

@@ -0,0 +1,27 @@
+# gulp documentation
+
+* [Writing a Plugin](writing-a-plugin/README.md) - So you're writing a gulp plugin? Go here for the essential dos and don'ts.
+* [gulp init](gulp-init.md) - Not sure how to format your plugin's README? Read on.
+
+## FAQ
+
+See [the FAQ](FAQ.md) for the answers to commonly asked questions.
+
+## Articles and Recipes
+
+* [Working with multiple sources in one task](recipes/using-multiple-sources-in-one-task.md)
+* [Mocha test runner with gulp](recipes/mocha-test-runner-with-gulp.md)
+* [Rebuild only files that change](recipes/rebuild-only-files-that-change.md)
+* [Introduction to node.js streams](https://github.com/substack/stream-handbook)
+
+## Presentations and slides
+
+* [Inspiration (slides)](http://slid.es/contra/gulp)
+
+## License
+
+All the documentation is covered by the CC0 license *(do whatever you want with it - public domain)*.
+
+[![CC0](http://i.creativecommons.org/p/zero/1.0/88x31.png)](http://creativecommons.org/publicdomain/zero/1.0/)
+
+To the extent possible under law, [Fractal](http://wearefractal.com) has waived all copyright and related or neighboring rights to this work.

docs/gulp-init.md

@@ -0,0 +1,18 @@
+# gulp-init
+
+Instead of having a `gulp init` command we chose to make a wiki page to get you started.
+
+Here is what a `gulp init` command would have done:
+
+1. Run `npm install gulp --save`
+2. Place the following code in gulpfile.js
+
+```javascript
+var gulp = require('gulp');
+
+gulp.task('default', function(){
+  // place code for your default task here
+});
+```
+
+See? Pretty simple. No need for a command.

docs/recipes/mocha-test-runner-with-gulp.md

@@ -0,0 +1,72 @@
+# Mocha test-runner with gulp
+
+### Passing shared module in all tests
+
+```
+var gulp = require('gulp');
+var mocha = require('gulp-mocha');
+ 
+gulp.task('tests', function() {
+    gulp.src(['test/test-*.js'], { read: false })
+        .pipe(mocha({
+            reporter: 'spec',
+            globals: {
+                should: require('should')
+            }
+        }));
+});
+```
+
+### Running mocha tests when files change
+
+With bundled `gulp.watch` and [`gulp-batch`](https://github.com/floatdrop/gulp-batch) (see readme of gulp-batch for reasons):
+
+```js
+// npm install gulp gulp-watch gulp-mocha gulp-batch
+
+var gulp = require('gulp');
+var mocha = require('gulp-mocha');
+var batch = require('gulp-batch');
+var gutil = require('gulp-util');
+
+gulp.task('mocha', function () {
+    return gulp.src(['test/*.js'], { read: false })
+        .pipe(mocha({ reporter: 'list' }))
+        .on('error', gutil.log);
+});
+
+gulp.watch(['lib/**', 'test/**'], batch(function(events, cb) {
+    gulp.run('mocha', cb);
+}));
+```
+
+With [`gulp-watch`](https://github.com/floatdrop/gulp-watch) plugin:
+
+```js
+// npm i gulp gulp-watch gulp-mocha
+
+var gulp = require('gulp');
+var mocha = require('gulp-mocha');
+var watch = require('gulp-watch');
+var gutil = require('gulp-util')
+
+gulp.task('mocha', function () {
+    return gulp.src(['test/*.js'], { read: false })
+        .pipe(mocha({ reporter: 'list' }))
+        .on('error', gutil.log);
+});
+
+gulp.task('watch', function() {
+    gulp.src(['lib/**', 'test/**'], { read: false })
+        .pipe(watch(function(events, cb) {
+            gulp.run('mocha', cb);
+        });
+});
+
+gulp.task('default', function () {
+    gulp.run('mocha');
+    gulp.run('watch');
+});
+
+// run `gulp watch` or just `gulp` for watching and rerunning tests
+```

docs/recipes/rebuild-only-files-that-change.md

@@ -0,0 +1,16 @@
+# Rebuild only files that change
+
+With [`gulp-watch`](https://github.com/floatdrop/gulp-watch):
+
+```js
+var gulp = require('gulp');
+var sass = require('gulp-sass');
+var watch = require('gulp-watch');
+
+gulp.task('default', function() {
+    return gulp.src('./sass/*.scss')
+        .pipe(watch())
+        .pipe(sass())
+        .pipe(gulp.dest('./dist/'));
+});
+```

docs/recipes/using-multiple-sources-in-one-task.md

@@ -0,0 +1,17 @@
+# Using multiple sources in one task
+
+```js
+// npm install gulp event-stream
+
+var gulp = require('gulp');
+var es = require('event-stream');
+
+gulp.task('test', function(cb) {
+    return es.concat(
+        gulp.src('bootstrap/js/*.js')
+            .pipe(gulp.dest('public/bootstrap')),
+        gulp.src('jquery.cookie/jquery.cookie.js')
+            .pipe(gulp.dest('public/jquery'))
+    );
+});
+```

docs/writing-a-plugin/README.md

@@ -0,0 +1,53 @@
+# Writing a plugin
+
+If you plan to create your own Gulp plugin, you will save time by reading the full documentation.
+
+* [Guidelines](guidelines.md) (a MUST read)
+* [Using buffers](using-buffers.md)
+* [Dealing with streams](dealing-with-streams.md)
+* [Testing](testing.md)
+* [README conventions](readme-conventions.md)
+
+## What it does
+
+### Streaming file objects
+
+A gulp plugin always returns a stream in [object mode](http://nodejs.org/api/stream.html#stream_object_mode) that does the following:
+
+1. Takes in [vinyl File objects](http://github.com/wearefractal/vinyl)
+2. Outputs [vinyl File objects](http://github.com/wearefractal/vinyl)
+
+These are known as [transform streams](http://nodejs.org/api/stream.html#stream_class_stream_transform_1) (also sometimes called through streams). Transform streams are streams that are readable and writable which manipulate objects as they're being passed through.
+
+### Modifying file content
+
+Vinyl files can have 3 possible forms for the contents attribute:
+
+- [Streams](dealing-with-streams.md)
+- [Buffers](using-buffers.md)
+- Empty (null) - Useful for things like rimraf, clean, where contents is not neeeded.
+
+## Useful resources
+
+* [File object](https://github.com/wearefractal/gulp-util/#new-fileobj)
+* [PluginError](https://github.com/gulpjs/gulp-util#new-pluginerrorpluginname-message-options)
+* [event-stream](https://github.com/dominictarr/event-stream)
+* [BufferStream](https://github.com/nfroidure/BufferStream)
+* [gulp-util](https://github.com/wearefractal/gulp-util)
+
+
+## Sample plugins
+
+* [sindresorhus' gulp plugins](https://github.com/search?q=%40sindresorhus+gulp-)
+* [Fractal's gulp plugins](https://github.com/search?q=%40wearefractal+gulp-)
+* [gulp-replace](https://github.com/lazd/gulp-replace)
+
+
+## About streams
+
+If you're unfamiliar with streams, you will need to read up on them:
+
+* https://github.com/substack/stream-handbook (a MUST read)
+* http://nodejs.org/api/stream.html
+
+Other libraries that are not file manipulating through streams but are made for use with gulp are tagged with the [gulpfriendly](https://npmjs.org/browse/keyword/gulpfriendly) keyword on npm.

docs/writing-a-plugin/dealing-with-streams.md

@@ -0,0 +1,69 @@
+# Dealing with streams
+
+> It is highly recommended to write plugins supporting streams. Here is some information on creating a gulp plugin that supports streams.
+
+[Writing a Plugin](README.md) > Writing stream based plugins
+
+## Dealing with streams
+
+Let's implement a plugin prepending some text to files. This plugin supports all possible forms of file.contents.
+
+```js
+var through = require('through');
+var gutil = require('gulp-util');
+var PluginError = gutil.PluginError;
+
+// Consts
+const PLUGIN_NAME = 'gulp-prefixer';
+
+function prefixStream(prefixText) {
+  var stream = through();
+  stream.write(prefixText);
+  return stream;
+}
+
+// Plugin level function (dealing with files)
+function gulpPrefixer(prefixText) {
+
+  if (!prefixText) {
+    throw PluginError(PLUGIN_NAME, "Missing prefix text!");
+  }
+  prefixText = new Buffer(prefixText); // allocate ahead of time
+
+  // Creating a stream through which each file will pass
+  var stream = through(function (file) {
+    if (file.isNull()) return this.queue(file); // Do nothing if no contents
+
+    if (file.isBuffer()) {
+      return this.emit('error', new PluginError(PLUGIN_NAME, 'Buffers not supported!'));
+    }
+
+    if (file.isStream()) {
+      file.contents = file.contents.pipe(prefixStream(prefixText));
+      return this.queue(file);
+    }
+  });
+
+  // returning the file stream
+  return stream;
+};
+
+// Exporting the plugin main function
+module.exports = gulpPrefixer;
+```
+
+The above plugin can be used like this:
+
+```js
+var gulp = require('gulp');
+var gulpPrefixer = require('gulp-prefixer');
+
+gulp.src('files/**/*.js')
+  .pipe(gulpPrefixer('prepended string'))
+  .pipe(gulp.dest('/modified-files/'));
+```
+
+## Some plugins using streams
+
+* [gulp-svgicons2svgfont](https://github.com/nfroidure/gulp-svgiconstosvgfont)
+* gulp-browserify (Soon)