diff --git a/docs/API.md b/docs/API.md index 017164bfb..5a9771bb1 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,3 +1,10 @@ + + Note: these docs are for version v4.0.0 (aka `gulp@next`) If you're on gulp v3.9.1, which is the current default `npm` release, you probably want [that version's documentation](https://github.com/gulpjs/gulp/blob/v3.9.1/docs/API.md). diff --git a/docs/CLI.md b/docs/CLI.md index c4af45f76..daa3f5d09 100644 --- a/docs/CLI.md +++ b/docs/CLI.md @@ -1,3 +1,10 @@ + + ## gulp CLI docs ### Flags @@ -105,7 +112,7 @@ Output: Command: `gulp --tasks-simple` -Output: +Output: ```shell one two diff --git a/docs/FAQ.md b/docs/FAQ.md index f8a649ead..9c89c143a 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,3 +1,10 @@ + + # FAQ ## Why gulp? Why not ____? diff --git a/docs/README.md b/docs/README.md index 4f8761b4a..d1b9f8c28 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,10 @@ + + # gulp documentation * [Getting Started](getting-started.md) - Get started with gulp diff --git a/docs/getting-started.md b/docs/getting-started.md index d5240cd1c..6cfe981b4 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,3 +1,10 @@ + + # Getting Started *If you've previously installed gulp globally, run `npm rm --global gulp` before following these instructions.* For more information, read this [Sip](https://medium.com/gulpjs/gulp-sips-command-line-interface-e53411d4467). diff --git a/docs/recipes/README.md b/docs/recipes/README.md index 3e822432a..e1ec37211 100644 --- a/docs/recipes/README.md +++ b/docs/recipes/README.md @@ -1,3 +1,10 @@ + + # Recipes * [Automate release workflow](automate-release-workflow.md) diff --git a/docs/recipes/automate-release-workflow.md b/docs/recipes/automate-release-workflow.md index 0f18006a9..3b929866a 100644 --- a/docs/recipes/automate-release-workflow.md +++ b/docs/recipes/automate-release-workflow.md @@ -1,3 +1,10 @@ + + # Automate release workflow If your project follows a semantic versioning, it may be a good idea to automatize the steps needed to do a release. diff --git a/docs/recipes/browserify-multiple-destination.md b/docs/recipes/browserify-multiple-destination.md index 474f58286..fa1b65cec 100644 --- a/docs/recipes/browserify-multiple-destination.md +++ b/docs/recipes/browserify-multiple-destination.md @@ -1,3 +1,10 @@ + + # Browserify + Globs (multiple destination) This example shows how to set up a task of bundling multiple entry points into multiple destinations using browserify. diff --git a/docs/recipes/browserify-transforms.md b/docs/recipes/browserify-transforms.md index 47a0d4d54..8659614ff 100644 --- a/docs/recipes/browserify-transforms.md +++ b/docs/recipes/browserify-transforms.md @@ -1,3 +1,10 @@ + + # Browserify + Transforms [Browserify](https://github.com/browserify/browserify) has become an important and indispensable diff --git a/docs/recipes/browserify-uglify-sourcemap.md b/docs/recipes/browserify-uglify-sourcemap.md index cccfec098..99800ed53 100644 --- a/docs/recipes/browserify-uglify-sourcemap.md +++ b/docs/recipes/browserify-uglify-sourcemap.md @@ -1,10 +1,17 @@ + + # Browserify + Uglify2 with sourcemaps [Browserify](https://github.com/browserify/browserify) has become an important and indispensable tool but requires being wrapped before working well with gulp. Below is a simple recipe for using Browserify with full sourcemaps that resolve to the original individual files. -See also: the [Combining Streams to Handle Errors](https://github.com/gulpjs/gulp/blob/master/docs/recipes/combining-streams-to-handle-errors.md) recipe for handling errors with browserify or uglify in your stream. +See also: the [Combining Streams to Handle Errors](https://github.com/gulpjs/gulp/blob/master/docs/recipes/combining-streams-to-handle-errors.md) recipe for handling errors with browserify or uglify in your stream. A simple `gulpfile.js` file for Browserify + Uglify2 with sourcemaps: diff --git a/docs/recipes/browserify-with-globs.md b/docs/recipes/browserify-with-globs.md index 72695fb6d..d9396f1b6 100644 --- a/docs/recipes/browserify-with-globs.md +++ b/docs/recipes/browserify-with-globs.md @@ -1,3 +1,10 @@ + + # Browserify + Globs [Browserify + Uglify2](https://github.com/gulpjs/gulp/blob/master/docs/recipes/browserify-uglify-sourcemap.md) shows how to setup a basic gulp task to bundle a JavaScript file with its dependencies, and minify the bundle with UglifyJS while preserving source maps. diff --git a/docs/recipes/combining-streams-to-handle-errors.md b/docs/recipes/combining-streams-to-handle-errors.md index 7c38654af..16b561669 100644 --- a/docs/recipes/combining-streams-to-handle-errors.md +++ b/docs/recipes/combining-streams-to-handle-errors.md @@ -1,3 +1,10 @@ + + # Combining streams to handle errors By default, emitting an error on a stream will cause it to be thrown unless it already has a listener attached to the `error` event. This gets a bit tricky when you're working with longer pipelines of streams. diff --git a/docs/recipes/cron-task.md b/docs/recipes/cron-task.md index 030fb334a..ad90a6f01 100644 --- a/docs/recipes/cron-task.md +++ b/docs/recipes/cron-task.md @@ -1,9 +1,16 @@ + + # Run gulp task via cron job While logged in via a user that has privileges to run `gulp`, run the following: crontab -e - + to edit your current "[crontab](https://en.wikipedia.org/wiki/Cron)" file. Typically, within a cron job, you want to run any binary using absolute paths, diff --git a/docs/recipes/delete-files-folder.md b/docs/recipes/delete-files-folder.md index 5f7cc1afd..731ae4f91 100644 --- a/docs/recipes/delete-files-folder.md +++ b/docs/recipes/delete-files-folder.md @@ -1,3 +1,9 @@ + # Delete files and folders diff --git a/docs/recipes/exports-as-tasks.md b/docs/recipes/exports-as-tasks.md index 2eaea4905..892c6bbf5 100644 --- a/docs/recipes/exports-as-tasks.md +++ b/docs/recipes/exports-as-tasks.md @@ -1,3 +1,10 @@ + + # Exports as Tasks Using the ES2015 module syntax you can use your exports as tasks. diff --git a/docs/recipes/fast-browserify-builds-with-watchify.md b/docs/recipes/fast-browserify-builds-with-watchify.md index b56469589..aa07f1a93 100644 --- a/docs/recipes/fast-browserify-builds-with-watchify.md +++ b/docs/recipes/fast-browserify-builds-with-watchify.md @@ -1,3 +1,10 @@ + + # Fast browserify builds with watchify As a [browserify](https://github.com/browserify/browserify) project begins to expand, the time to bundle it slowly gets longer and longer. While it might start at 1 second, it's possible to be waiting 30 seconds for your project to build on particularly large projects. @@ -24,7 +31,7 @@ var customOpts = { debug: true }; var opts = assign({}, watchify.args, customOpts); -var b = watchify(browserify(opts)); +var b = watchify(browserify(opts)); // add transformations here // i.e. b.transform(coffeeify); diff --git a/docs/recipes/handling-the-delete-event-on-watch.md b/docs/recipes/handling-the-delete-event-on-watch.md index 05bd683a1..ba7a77cd3 100644 --- a/docs/recipes/handling-the-delete-event-on-watch.md +++ b/docs/recipes/handling-the-delete-event-on-watch.md @@ -1,3 +1,10 @@ + + # Handling the Delete Event on Watch You can listen for `'unlink'` events to fire on the watcher returned from `gulp.watch`. diff --git a/docs/recipes/incremental-builds-with-concatenate.md b/docs/recipes/incremental-builds-with-concatenate.md index c9fdaa0de..797bd0cab 100644 --- a/docs/recipes/incremental-builds-with-concatenate.md +++ b/docs/recipes/incremental-builds-with-concatenate.md @@ -1,3 +1,10 @@ + + # Incremental rebuilding, including operating on full file sets The trouble with incremental rebuilds is you often want to operate on _all_ processed files, not just single files. For example, you may want to lint and module-wrap just the file(s) that have changed, then concatenate it with all other linted and module-wrapped files. This is difficult without the use of temp files. diff --git a/docs/recipes/maintain-directory-structure-while-globbing.md b/docs/recipes/maintain-directory-structure-while-globbing.md index aadd32ef4..279eac11d 100644 --- a/docs/recipes/maintain-directory-structure-while-globbing.md +++ b/docs/recipes/maintain-directory-structure-while-globbing.md @@ -1,9 +1,16 @@ + + # Maintain Directory Structure while Globbing If you are planning to read a few files/folders from a directory and maintain their relative path, you need to pass `{base: '.'}` as the second argument to `gulp.src()`. -For example, if you have a directory structure like +For example, if you have a directory structure like ![Dev setup](https://cloud.githubusercontent.com/assets/2562992/3178498/bedf75b4-ec1a-11e3-8a71-a150ad94b450.png) @@ -27,18 +34,17 @@ If you want to maintain the structure, you need to pass `{base: '.'}` to `gulp.s ```js gulp.task('task', function () { - return gulp.src(['index.html', - 'css/**', - 'js/**', - 'lib/**', - 'images/**', + return gulp.src(['index.html', + 'css/**', + 'js/**', + 'lib/**', + 'images/**', 'plugin/**' ], {base: '.'}) .pipe(operation1()) .pipe(operation2()); }); ``` -And the input to your `operation1()` will be a folder structure like +And the input to your `operation1()` will be a folder structure like ![with-base](https://cloud.githubusercontent.com/assets/2562992/3178607/053d6722-ec1c-11e3-9ba8-7ce39e1a480e.png) - diff --git a/docs/recipes/make-stream-from-buffer.md b/docs/recipes/make-stream-from-buffer.md index f11c11612..b376eafce 100644 --- a/docs/recipes/make-stream-from-buffer.md +++ b/docs/recipes/make-stream-from-buffer.md @@ -1,3 +1,10 @@ + + # Make stream from buffer (memory contents) Sometimes you may need to start a stream with files that their contents are in a variable and not in a physical file. In other words, how to start a 'gulp' stream without using `gulp.src()`. @@ -78,9 +85,9 @@ gulp.task('write-versions', function() { availableVersions.forEach(function(v) { // make a new stream with fake file name var stream = source('final.' + v); - + var streamEnd = stream; - + // we load the data from the concatenated libs var fileContents = memory['libs.concat.js'] + // we add the version's data @@ -99,11 +106,11 @@ gulp.task('write-versions', function() { .pipe(vinylBuffer()) //.pipe(tap(function(file) { /* do something with the file contents here */ })) .pipe(gulp.dest('output')); - + // add the end of the stream, otherwise the task would finish before all the processing // is done streams.push(streamEnd); - + }); return es.merge.apply(this, streams); diff --git a/docs/recipes/minified-and-non-minified.md b/docs/recipes/minified-and-non-minified.md index e1a6a4296..3cc603a9e 100644 --- a/docs/recipes/minified-and-non-minified.md +++ b/docs/recipes/minified-and-non-minified.md @@ -1,3 +1,10 @@ + + # Output both a minified and non-minified version Outputting both a minified and non-minified version of your combined JavaScript files can be achieved by using `gulp-rename` and piping to `dest` twice (once before minifying and once after minifying): diff --git a/docs/recipes/minimal-browsersync-setup-with-gulp4.md b/docs/recipes/minimal-browsersync-setup-with-gulp4.md index ec22c0717..55a5ac38c 100644 --- a/docs/recipes/minimal-browsersync-setup-with-gulp4.md +++ b/docs/recipes/minimal-browsersync-setup-with-gulp4.md @@ -1,3 +1,10 @@ + + # Minimal BrowserSync setup with Gulp 4 [BrowserSync](https://www.browsersync.io/) is a great tool to streamline diff --git a/docs/recipes/mocha-test-runner-with-gulp.md b/docs/recipes/mocha-test-runner-with-gulp.md index c6ca3873f..eab0725cd 100644 --- a/docs/recipes/mocha-test-runner-with-gulp.md +++ b/docs/recipes/mocha-test-runner-with-gulp.md @@ -1,3 +1,10 @@ + + # Mocha test-runner with gulp ### Passing shared module in all tests diff --git a/docs/recipes/only-pass-through-changed-files.md b/docs/recipes/only-pass-through-changed-files.md index 1b0a34496..64d16dbe7 100644 --- a/docs/recipes/only-pass-through-changed-files.md +++ b/docs/recipes/only-pass-through-changed-files.md @@ -1,3 +1,10 @@ + + # Only pass through changed files Files are passed through the whole pipe chain on every run by default. By using [gulp-changed](https://github.com/sindresorhus/gulp-changed) only changed files will be passed through. This can speed up consecutive runs considerably. diff --git a/docs/recipes/pass-arguments-from-cli.md b/docs/recipes/pass-arguments-from-cli.md index 1f9c74b14..40c44bc15 100644 --- a/docs/recipes/pass-arguments-from-cli.md +++ b/docs/recipes/pass-arguments-from-cli.md @@ -1,3 +1,10 @@ + + # Pass arguments from the command line ```js diff --git a/docs/recipes/rebuild-only-files-that-change.md b/docs/recipes/rebuild-only-files-that-change.md index 245ddc4fb..d60a80257 100644 --- a/docs/recipes/rebuild-only-files-that-change.md +++ b/docs/recipes/rebuild-only-files-that-change.md @@ -1,3 +1,10 @@ + + # Rebuild only files that change With [`gulp-watch`](https://github.com/floatdrop/gulp-watch): diff --git a/docs/recipes/rollup-with-rollup-stream.md b/docs/recipes/rollup-with-rollup-stream.md index 24679d557..4c77aacc1 100644 --- a/docs/recipes/rollup-with-rollup-stream.md +++ b/docs/recipes/rollup-with-rollup-stream.md @@ -1,3 +1,10 @@ + + # Rollup with rollup-stream Like Browserify, [Rollup](https://rollupjs.org/) is a bundler and thus only fits naturally into gulp if it's at the start of the pipeline. Unlike Browserify, Rollup doesn't natively produce a stream as output and needs to be wrapped before it can take this position. [rollup-stream](https://github.com/Permutatrix/rollup-stream) does this for you, producing output just like that of Browserify's `bundle()` method—as a result, most of the Browserify recipes here will also work with rollup-stream. diff --git a/docs/recipes/run-grunt-tasks-from-gulp.md b/docs/recipes/run-grunt-tasks-from-gulp.md index ddf137d66..ee633125f 100644 --- a/docs/recipes/run-grunt-tasks-from-gulp.md +++ b/docs/recipes/run-grunt-tasks-from-gulp.md @@ -1,3 +1,10 @@ + + # Run Grunt Tasks from Gulp It is possible to run Grunt tasks / Grunt plugins from within Gulp. This can be useful during a gradual migration from Grunt to Gulp or if there's a specific plugin that you need. With the described approach no Grunt CLI and no Gruntfile is required. @@ -32,7 +39,7 @@ gulp.task('copy', function (done) { ``` -Now start the task with: +Now start the task with: `gulp copy` With the aforementioned approach the grunt tasks get registered within gulp's task system. **Keep in mind grunt tasks are usually blocking (unlike gulp), therefore no other task (not even a gulp task) can run until a grunt task is completed.** diff --git a/docs/recipes/running-shell-commands.md b/docs/recipes/running-shell-commands.md index 5d3447476..7bc4eb1fe 100644 --- a/docs/recipes/running-shell-commands.md +++ b/docs/recipes/running-shell-commands.md @@ -1,3 +1,10 @@ + + # Running Shell Commands Sometimes it is helpful to be able to call existing command line tools from gulp. diff --git a/docs/recipes/running-task-steps-per-folder.md b/docs/recipes/running-task-steps-per-folder.md index df5c53695..5ee3b6490 100644 --- a/docs/recipes/running-task-steps-per-folder.md +++ b/docs/recipes/running-task-steps-per-folder.md @@ -1,3 +1,10 @@ + + # Generating a file per folder If you have a set of folders, and wish to perform a set of tasks on each, for instance... @@ -44,11 +51,11 @@ gulp.task('scripts', function(done) { // concat into foldername.js .pipe(concat(folder + '.js')) // write to output - .pipe(gulp.dest(scriptsPath)) + .pipe(gulp.dest(scriptsPath)) // minify .pipe(uglify()) // rename to folder.min.js - .pipe(rename(folder + '.min.js')) + .pipe(rename(folder + '.min.js')) // write to output again .pipe(gulp.dest(scriptsPath)); }); diff --git a/docs/recipes/running-tasks-in-series.md b/docs/recipes/running-tasks-in-series.md index b28e692a3..be60816fb 100644 --- a/docs/recipes/running-tasks-in-series.md +++ b/docs/recipes/running-tasks-in-series.md @@ -1,3 +1,10 @@ + + # Running tasks in series By default, gulp CLI run tasks with maximum concurrency - e.g. it launches diff --git a/docs/recipes/server-with-livereload-and-css-injection.md b/docs/recipes/server-with-livereload-and-css-injection.md index a23cc239d..51b652268 100644 --- a/docs/recipes/server-with-livereload-and-css-injection.md +++ b/docs/recipes/server-with-livereload-and-css-injection.md @@ -1,3 +1,10 @@ + + # Server with live-reloading and CSS injection With [BrowserSync](https://browsersync.io) and gulp, you can easily create a development server that is accessible to any device on the same WiFi network. BrowserSync also has live-reload built in, so there's nothing else to configure. diff --git a/docs/recipes/sharing-streams-with-stream-factories.md b/docs/recipes/sharing-streams-with-stream-factories.md index 16c110a06..932085235 100644 --- a/docs/recipes/sharing-streams-with-stream-factories.md +++ b/docs/recipes/sharing-streams-with-stream-factories.md @@ -1,3 +1,10 @@ + + # Sharing streams with stream factories If you use the same plugins in multiple tasks you might find yourself getting that itch to DRY things up. This method will allow you to create factories to split out your commonly used stream chains. diff --git a/docs/recipes/specifying-a-cwd.md b/docs/recipes/specifying-a-cwd.md index eba0ceca9..b6306d6a4 100644 --- a/docs/recipes/specifying-a-cwd.md +++ b/docs/recipes/specifying-a-cwd.md @@ -1,3 +1,10 @@ + + # Specifying a new cwd (current working directory) This is helpful for projects using a nested directory structure, such as: diff --git a/docs/recipes/split-tasks-across-multiple-files.md b/docs/recipes/split-tasks-across-multiple-files.md index afee1be10..efdd942fa 100644 --- a/docs/recipes/split-tasks-across-multiple-files.md +++ b/docs/recipes/split-tasks-across-multiple-files.md @@ -1,3 +1,10 @@ + + # Split tasks across multiple files If your `gulpfile.js` is starting to grow too large, you can split the tasks diff --git a/docs/recipes/templating-with-swig-and-yaml-front-matter.md b/docs/recipes/templating-with-swig-and-yaml-front-matter.md index 50c98e5f7..dbda0ad14 100644 --- a/docs/recipes/templating-with-swig-and-yaml-front-matter.md +++ b/docs/recipes/templating-with-swig-and-yaml-front-matter.md @@ -1,3 +1,10 @@ + + # Templating with Swig and YAML front-matter Templating can be setup using `gulp-swig` and `gulp-front-matter`: diff --git a/docs/recipes/using-external-config-file.md b/docs/recipes/using-external-config-file.md index b073f1dfc..4a2215d48 100644 --- a/docs/recipes/using-external-config-file.md +++ b/docs/recipes/using-external-config-file.md @@ -1,3 +1,10 @@ + + # Using external config file Beneficial because it's keeping tasks DRY and config.json can be used by another task runner, like `grunt`. diff --git a/docs/recipes/using-multiple-sources-in-one-task.md b/docs/recipes/using-multiple-sources-in-one-task.md index 39e3e3b23..6e5622ec4 100644 --- a/docs/recipes/using-multiple-sources-in-one-task.md +++ b/docs/recipes/using-multiple-sources-in-one-task.md @@ -1,3 +1,10 @@ + + # Using multiple sources in one task ```js diff --git a/docs/why-use-pump/README.md b/docs/why-use-pump/README.md index de6ebc85f..c4810725b 100644 --- a/docs/why-use-pump/README.md +++ b/docs/why-use-pump/README.md @@ -1,3 +1,10 @@ + + # Why Use Pump? When using `pipe` from the Node.js streams, errors are not propagated forward diff --git a/docs/writing-a-plugin/README.md b/docs/writing-a-plugin/README.md index bcd708356..d876250cd 100644 --- a/docs/writing-a-plugin/README.md +++ b/docs/writing-a-plugin/README.md @@ -1,3 +1,10 @@ + + # Writing a plugin If you plan to create your own Gulp plugin, you will save time by reading the full documentation. diff --git a/docs/writing-a-plugin/dealing-with-streams.md b/docs/writing-a-plugin/dealing-with-streams.md index fd518bd66..d1ad36a87 100644 --- a/docs/writing-a-plugin/dealing-with-streams.md +++ b/docs/writing-a-plugin/dealing-with-streams.md @@ -1,3 +1,10 @@ + + # Dealing with streams > It is highly recommended to write plugins supporting streams. Here is some information on creating a gulp plugin that supports streams. @@ -75,4 +82,3 @@ gulp.src('files/**/*.js', { buffer: false }) ## Some plugins using streams * [gulp-svgicons2svgfont](https://github.com/nfroidure/gulp-svgiconstosvgfont) - diff --git a/docs/writing-a-plugin/guidelines.md b/docs/writing-a-plugin/guidelines.md index b810ad8a1..a1d626c93 100644 --- a/docs/writing-a-plugin/guidelines.md +++ b/docs/writing-a-plugin/guidelines.md @@ -1,3 +1,10 @@ + + # Guidelines > While these guidelines are totally optional, we **HIGHLY** recommend that everyone follows them. Nobody wants to use a bad plugin. These guidelines will actually help make your life easier by giving you assurance that your plugin fits well within gulp. diff --git a/docs/writing-a-plugin/recommended-modules.md b/docs/writing-a-plugin/recommended-modules.md index 0b49b39d4..a2faa94ce 100644 --- a/docs/writing-a-plugin/recommended-modules.md +++ b/docs/writing-a-plugin/recommended-modules.md @@ -1,3 +1,10 @@ + + # Recommended Modules > Sticking to this curated list of recommended modules will make sure you don't violate the plugin guidelines and ensure consistency across plugins. diff --git a/docs/writing-a-plugin/testing.md b/docs/writing-a-plugin/testing.md index 487a87f95..cc9f98469 100644 --- a/docs/writing-a-plugin/testing.md +++ b/docs/writing-a-plugin/testing.md @@ -1,3 +1,10 @@ + + # Testing > Testing your plugin is the only way to ensure quality. It brings confidence to your users and makes your life easier. diff --git a/docs/writing-a-plugin/using-buffers.md b/docs/writing-a-plugin/using-buffers.md index e35e41b59..b7ea05548 100644 --- a/docs/writing-a-plugin/using-buffers.md +++ b/docs/writing-a-plugin/using-buffers.md @@ -1,3 +1,10 @@ + + # Using buffers > Here is some information on creating gulp plugin that manipulates buffers.