# grunt-html

> Grunt plugin for HTML validation, using the Nu Html Checker (v.Nu)

Latest version **18.1.0** (published 2026-05-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install grunt-html
pnpm add grunt-html
yarn add grunt-html
bun add grunt-html
```

## Health

**Score 45/100 (D)** — status: active.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 18.1.0 |
| Published | 2026-05-08 |
| First published | 2012-04-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=18 |
| Dependencies | 3 |
| Unpacked size | 22 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | Jörn Zaefferer |
| Maintainers | jzaefferer, nschonni, xhmikosr, sideshowbarker |
| Keywords | gruntplugin |

## Links

- npm: https://www.npmjs.com/package/grunt-html
- Repository: https://github.com/validator/grunt-html
- Issues: https://github.com/validator/grunt-html/issues
- npm.io page: https://npm.io/package/grunt-html

## Dependencies (3)

- [async](https://npm.io/package/async.md) ^3.2.6
- [vnu-jar](https://npm.io/package/vnu-jar.md) 25.11.3
- [picocolors](https://npm.io/package/picocolors.md) ^1.1.1

## Recent versions

- 18.1.0 (latest) — 2026-05-08
- 18.0.2 — 2025-11-03
- 18.0.1 — 2025-11-03
- 18.0.0 — 2025-11-02
- 17.1.0 — 2024-10-22
- 17.0.1 — 2024-08-13
- 17.0.0 — 2023-04-11
- 16.0.0 — 2022-10-02
- 15.2.2 — 2022-02-09
- 15.2.1 — 2022-02-09
- 15.2.0 — 2022-02-09
- 15.1.0 — 2021-10-13
- 15.0.2 — 2021-10-05
- 15.0.1 — 2021-09-16
- 15.0.0 — 2021-09-15
- … 66 more at https://npm.io/package/grunt-html/versions

## README

# grunt-html

[![npm version](https://img.shields.io/npm/v/grunt-html?logo=npm&logoColor=fff)](https://www.npmjs.com/package/grunt-html)
[![Build Status](https://img.shields.io/github/actions/workflow/status/validator/grunt-html/test.yml?branch=main&label=Tests&logo=github)](https://github.com/validator/grunt-html/actions/workflows/test.yml?query=branch%3Amain)
[![Coverage Status](https://img.shields.io/coveralls/github/validator/grunt-html/main?logo=coveralls&logoColor=fff)](https://coveralls.io/github/validator/grunt-html?branch=main)

[Grunt][grunt] plugin for HTML validation, using the [Nu Html Checker (v.Nu)][vnujar].

## Getting Started

Install this grunt plugin next to your project's [Gruntfile.js][getting_started] with:

```bash
npm install grunt-html -D
```

Then add this line to your project's `Gruntfile.js`:

```js
grunt.loadNpmTasks('grunt-html');
```

Then specify what files to validate in your config:

```js
grunt.initConfig({
  htmllint: {
    all: ['demos/**/*.html', 'tests/**/*.html']
  }
});
```

For fast validation, keep that in a single group, as the validator initialization takes a few seconds.

When combined with a watching task (such as [grunt-contrib-watch][watch]), even faster validation can be achieved by starting the validator in client mode and connecting to an already-running instance of the validator in server mode. This removes the time required by repeated initializations. See the `server` option below.

## Options

### `errorlevels`

* Type: `Array`
* Default: `['info', 'warning', 'error']`

Set `errorlevels` to control which error types are returned from the validator. Ignores all other returned types.

### `force`

* Type: `Boolean`
* Default: `false`

Set `force` to `true` to report errors but not fail the `grunt` task.

### `ignore`

* Type: `Array`, `String`, or `RegExp`
* Default: `null`

Use this to specify the error message(s) to ignore. For example:

```js
all: {
  options: {
    ignore: 'The “clear” attribute on the “br” element is obsolete. Use CSS instead.'
  },
  src: 'html4.html'
}
```

The `ignore` option also supports regular expressions. For example, to ignore AngularJS directive attributes:

```js
all: {
  options: {
    ignore: /attribute “ng-[a-z-]+” not allowed/
  },
  src: 'app.html'
}
```

### `noLangDetect`

* Type: `Boolean`
* Default: `false`

Set `noLangDetect` to `true` to [skip the checking of the language of the page](https://github.com/validator/validator#--no-langdetect).

### `reporter`

* Type: `String`
* Default: `null`

Allows you to modify the output format. By default, this plugin will use a built-in Grunt reporter. Set the path to your own custom reporter or to one of the provided reporters: `checkstyle`, `junit` or `json`.

### `reporterOutput`

* Type: `String`
* Default: `null`

Specify a filepath to output the results of a reporter. If `reporterOutput` is specified then all output will be written to the given filepath rather than printed to `stdout`.

### `absoluteFilePathsForReporter`

* Type: `Boolean`
* Default: `false`

Set `absoluteFilePathsForReporter` to `true` to use absolute file paths in generated reports.

### `server`

* Type: `Object`, or a falsy value
* Default: `false`

When `server` is set to a falsy value, the validator is invoked using `java -jar`, which can be considered normal operation.

Set `server` to an object to start the validator in client mode and connect to an already-running instance of the validator in server mode.

To start the validator in server mode, use `java -cp "path/to/vnu.jar" nu.validator.servlet.Main <port>`.

```js
all: {
  options: {
    // connect to a validator instance running in server mode on localhost:8888
    server: {}
  },
  src: 'app.html'
}
```

The `server` object also accepts the `host` and `port` keys, specifying the location of the server.

```js
all: {
  options: {
    server: {
      // your team's local dev tool machine, for example
      host: '192.168.0.5',
      port: 8877
    }
  },
  src: 'app.html'
}
```

The following configuration in Gruntfile.js uses [grunt-vnuserver][vnuserver] to start the validator in server mode and sets up a watch task to run `htmllint` every time the source file changes.
By starting the validator in server mode once using the `vnuserver` task, validations by `htmllint` can be performed much faster by simply connecting to this already-running server.

```js
module.exports = function (grunt) {
  grunt.initConfig({
    vnuserver: {
    },
    htmllint: {
      all: {
        options: {
          server: {}
        },
        src: 'app.html'
      }
    },
    watch: {
      all: {
        tasks: ['htmllint'],
        files: 'app.html'
      }
    }
  });

  grunt.loadNpmTasks('grunt-vnuserver');
  grunt.loadNpmTasks('grunt-html');
  grunt.loadNpmTasks('grunt-contrib-watch');

  grunt.registerTask('default', ['vnuserver', 'watch']);
};
```

### `threads`

* Type: `String`, `Boolean`, `Number`
* Default: `auto`, which is the number of threads -1

Use this option to control the number of threads that grunt-html will use when validating a big number of files. This will spawn as many Java processes as the number of threads.

## Potential pitfalls

* vnu.jar requires Java 8 environment or up.

## License

Copyright Jörn Zaefferer. Licensed under the [MIT license](LICENSE).

[grunt]: https://gruntjs.com/
[getting_started]: https://gruntjs.com/getting-started
[vnujar]: https://validator.github.io/validator/
[watch]: https://github.com/gruntjs/grunt-contrib-watch
[vnuserver]: https://www.npmjs.com/package/grunt-vnuserver

---
_Source: https://npm.io/package/grunt-html · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._