html-validate

html-validate

Offline HTML5 validator. Validates either a full document or a smaller (incomplete) template, e.g. from an AngularJS or Vue.js component.

Features

• Can test fragments of HTML, for instance a component template.
• Does not upload any data to a remote server, all testing is done locally.
• Strict and non-forgiving parsing. It will not try to correct any incorrect markup or guess what it should do.

Usage

npm install -g html-validate
html-validate [OPTIONS] [FILENAME..] [DIR..]

Configuration

Create .htmlvalidate.json:

{
  "extends": [
    "html-validate:recommended"
  ],

  "rules": {
    "close-order": "error",
    "void": ["warn", {"style": "omit"}]
  }
}

Example

<p>
  <button>Click me!</button>
  <div id="show-me">
    Lorem ipsum
  </div>
</p>

  1:1  error  Element <p> is implicitly closed by adjacent <div>  no-implicit-close
  2:2  error  Button is missing type attribute                    button-type
  6:4  error  Unexpected close-tag, expected opening tag          close-order

Bundles

The library comes in four flavours:

• CommonJS full (dist/cjs/main.js)
• CommonJS browser (dist/cjs/browser.js)
• ESM full (dist/es/main.js)
• ESM browser (dist/es/browser.js)

The browser versions contains a slimmed version without CLI dependencies. Your tooling will probably use the correct version but if needed you can import the files directly.

Do note that to run in a browser you still need to polyfill the fs nodejs library.

Browsers and bundlers are currently not 100% supported but is possible with some tricks, see running in browser for more details.

Developing

Prerequisites

• NodeJS 12
• NPM 7

Generated files

Some files are automatically generated by the toolchain but are required by many other steps such as testing and linting. This normally happens during npm run build and npm install. If you need to manually regenerate the files use:

npm run codegen

Test

Testing is done using jest.

npm test

or call jest directly.

Some tests are autogenerated from documentation examples, use npm run docs to build those before running.

Lint

Linting is done using ESLint.

npm run eslint

or call eslint directly.

Build

npm run build

To build documentation use:

npm run docs

The documentation can be served locally using:

npm start

Changelog

8.0.0 (2023-06-04)

⚠ BREAKING CHANGES

See {@link migration migration guide} for details.

• api: The ConfigFactory parameter to ConfigLoader (and its child classes StaticConfigLoader and FileSystemConfigLoader) has been removed. No replacement.

If you are using this you are probably better off implementing a fully custom loader later returning a ResolvedConfig.

• api: A new getContextualDocumentation replaces the now deprecated getRuleDocumentation method. The context parameter to getRuleDocumentation is now required and must not be omitted.

For rule authors this means you can now rely on the context parameter being set in the documentation callback.

For IDE integration and toolchain authors this means you should migrate to use getContextualDocumentation as soon as possible or if you are continuing to use getRuleDocumentation you are now required to pass the config and context field from the reported message.

• api: This change affect API users only, specifically API users directly using the Config class. Additionally when using the StaticConfigLoader no modules will be resolved using require(..) by default any longer. Instructions for running in a browser is also updated, see below.

To create a Config instance you must now pass in a Resolver (single or array):

+const resolvers = [ /* ... */ ];
-const config = new Config( /* ... */ );
+const config = new Config(resolvers, /* ... */ );

This applies to calls to Config.fromObject(..) as well.

The default resolvers for StaticConfigLoader is StaticResolver and for FileSystemConfigLoader is NodeJSResolver. Both can optionally take a new set of resolvers (including custom ones).

Each resolver will, in order, try to load things by name. For instance, when using the NodeJSResolver it uses require(..) to load new items.

• NodeJSResolver - uses require(..)
• StaticResolver - uses a predefined set of items.
• api: The HtmlValidate class now has a Promise based API where most methods return a promise. The old synchronous methods are renamed.

Either adapt to the new asynchronous API:

-const result = htmlvalidate.validateFile("my-awesome-file.html");
+const result = await htmlvalidate.validateFile("my-awesome-file.html");

or migrate to the synchronous API:

-const result = htmlvalidate.validateFile("my-awesome-file.html");
+const result = htmlvalidate.validateFileSync("my-awesome-file.html");

For unittesting with Jest it is recommended to make the entire test-case async:

-it("my awesome test", () => {
+it("my awesome test", async () => {
   const htmlvalidate = new HtmlValidate();
-  const report = htmlvalidate.validateString("...");
+  const report = await htmlvalidate.validateString("...");
   expect(report).toMatchCodeFrame();
});

• api: ConfigLoader must return ResolvedConfig. This change affects API users who implements custom configuration loaders.

In the simplest case this only requires to call Config.resolve():

-return config;
+return config.resolve();

A resolved configuration cannot further reference any new files to extend, plugins to load, etc.

• api: The TemplateExtractor class has been moved to the @html-validate/plugin-utils package. This change only affects API users who use the TemplateExtractor class, typically this is only used when writing plugins.
• config: Deprecated severity alias disabled removed. If you use this in your configuration you need to update it to off.

 {
   "rules": {
-    "my-awesome-rule": "disabled"
+    "my-awesome-rule": "off"
   }
 }

• rules: The void rule has been removed after being deprecated a long time, it is replaced with the separate void-content, void-style and no-self-closing rules.
• deps: minimum required node version is v16
• deps: minimum required jest version is v27

Features

• api: ConfigLoader must return ResolvedConfig (d685e6a)
• api: FileSystemConfigLoader supports passing a custom fs-like object (fac704e)
• api: add Promise based API to HtmlValidate class (adc7783)
• api: add Resolver classes as a mean to separate fs from browser build (3dc1724)
• api: new getContextualDocumentation to replace getRuleDocumentation (60c9a12)
• api: remove ConfigFactory (e309d89)
• api: remove TemplateExtractor in favour of @html-validate/plugin-utils (a0a512b)
• deps: minimum required jest version is v27 (dc79b6b)
• deps: minimum required node version is v16 (f6ccdb0)
• rules: remove deprecated void rule (3e727d8)

Bug Fixes

• config: remove deprecated severity alias disabled (6282293)