| :no_entry_sign:&nbsp; Gulp is no longer maintained.<br>The same functionality of this gulp plugin is available as a regular CLI build task without gulp.<br>See: [w3c-html-validator](https://github.com/center-key/w3c-html-validator) |
| :- |

# gulp-w3c-html-validator
<img src=https://centerkey.com/graphics/center-key-logo.svg align=right width=200 alt=logo>

_Gulp plugin to validate HTML using the W3C Markup Validation Service_

[![License:MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/center-key/gulp-w3c-html-validator/blob/main/LICENSE.txt)
[![npm](https://img.shields.io/npm/v/gulp-w3c-html-validator.svg)](https://www.npmjs.com/package/gulp-w3c-html-validator)
[![Build](https://github.com/center-key/gulp-w3c-html-validator/workflows/build/badge.svg)](https://github.com/center-key/gulp-w3c-html-validator/actions/workflows/run-spec-on-push.yaml)

This Gulp plugin is a wrapper for [w3c-html-validator](https://github.com/center-key/w3c-html-validator) (_"A package for testing HTML files or URLs against the W3C validator"_).&nbsp;
Note that it's usually simpler and cleaner to use the underlying library directly from
your **package.json** file than using this plugin.

<img src=https://raw.githubusercontent.com/center-key/gulp-w3c-html-validator/main/screenshot.png alt=screenshot>

## A) Setup
Install module into your project:
```shell
$ npm install --save-dev gulp-w3c-html-validator
```

## B) Define Task
Create a task in your **gulpfile.js**:
```javascript
// Imports
import gulp from 'gulp';
import { htmlValidator } from 'gulp-w3c-html-validator';

// Tasks
const task = {
   validateHtml() {
      return gulp.src('target/**/*.html')
         .pipe(htmlValidator.analyzer())
         .pipe(htmlValidator.reporter());
      },
   };

// Gulp
gulp.task('validate-html', task.validateHtml);
```

## C) Options
### 1. analyzer()
| Name (key)       | Type                    | Default                          | Description                                                          |
| :--------------- | :---------------------- | :------------------------------- | :------------------------------------------------------------------- |
| `checkUrl`       | **string**              | `'https://validator.w3.org/nu/'` | W3C validation API endpoint.                                         |
| `ignoreLevel`    | `'info'` or `'warning'` | `null`                           | Skip unwanted messages.*                                             |
| `ignoreMessages` | **string** or **regex** | `null`                           | Skip messages containing a string or matching a regular expression.* |

*The `ignoreMessages` and `ignoreLevel` options only work for `'json'` output.&nbsp;
Option value `'warning'` also skips `'info'`.

Example usage of `ignoreMessages` option:
```javascript
// Tasks
const task = {
   validateHtml() {
      return gulp.src('target/**/*.html')
         .pipe(htmlValidator.analyzer({ ignoreMessages: /^Duplicate ID/ }))
         .pipe(htmlValidator.reporter());
      },
   };
```

### 2. reporter()
| Name (key)      | Type        | Default | Description                                                                           |
| --------------- | ----------- | --------| ------------------------------------------------------------------------------------- |
| `maxMessageLen` | **number**  | `null`  | Trim validation messages to not exceed a maximum length.                              |
| `throwErrors`   | **boolean** | `false` | Throw an [error](https://github.com/gulpjs/plugin-error) for HTTP validation failure. |

## D) Custom Reporting
The `analyzer()` adds the validation results onto each file object in the `w3cHtmlValidator` field,
which contains a `validates` (**boolean**) field and a `messages` (**array**) field.

### Example usage
```javascript
// Import
import { htmlValidator } from 'gulp-w3c-html-validator';
import through2 from 'through2';

// Tasks
const task = {
   validateHtml() {
      const handleFile = (file, encoding, callback) => {
         callback(null, file);
         if (!file.w3cHtmlValidator.validates)
            throw Error('HTML failed validation');
         };
      return gulp.src('target/**/*.html')
         .pipe(htmlValidator.analyzer())
         .pipe(through2.obj(handleFile));  //custom reporter
      },
   };

// Gulp
gulp.task('validate-html', task.validateHtml);
```

<br>

---
[MIT License](LICENSE.txt)