@mitsue/vlint

A linter for HTML and CSS using Nu Html Checker.

Usage

1. Install vlint

   npm i --save-dev @mitsue/vlint

2. Put .vlintrc.yml in your project directory.

   html:
       vnu: https://example.com/nu/
   css:
       vnu: https://example.com/nu/

   Note: vlint transmits your content to Nu Html Checker.

3. Run vlint

   # html
   # HTML files (extension is either .htm, .html, or .shtml) will be checked.
   npx vlint
   
   # css
   # CSS files (extension is .css) will be checked.
   npx vlint --css

Configuring

vlint can be configured from a .vlintrc.yml.

html:
    vnu: https://example.com/nu/
    validator: https://example.com/check
    timeout: 30000
    charset: utf-8
    include: '**/*.+(htm|html|shtml)'
    ignore:
        - '**/node_modules/**'
css:
    vnu: https://example.com/nu/
    timeout: 120000
    charset: utf-8
    include: '**/*.css'
    ignore:
        - '**/node_modules/**'

• vnu

  URL of Nu Html Checker

  Default: no default value. This must be specified.

• validator

  URL of W3C Markup Validator. If this option is specified, XHTML 1.0, HTML 4.01 and so on are validated by W3C Markup Validator.

  HTML files which are not supported by W3C Markup Validator are validated by Nu Html Checker even if this option is specified.

  Specifying this option for css has no effect. CSS files are validated by Nu Html Checker even if this option is specified.

  Default: no default value.

• timeout

  Time to wait for a response from the network in milliseconds. Set 0 to disable timeout.

  Default: 30,000 (HTML) or 120,000 (CSS)

• charset

  Encoding (charset) of the file. If this option is omitted, Nu Html Checker detects encoding automatically.

  Default: no default value.

• include

  glob pattern of HTML or CSS. This can be a string or an array of strings.

  Default: **/*.+(htm|html|shtml) (HTML) or **/*.css (CSS)

• ignore

  glob pattern of files which are ignored by vlint. This can be a string or an array of strings.

  Default: [**/node_modules/**]

Cache

vlint can cache the result of the Nu Html Checker. The cache allows vlint to validate only changed files. This will improve vlint's performance in most cases.

vlint --cache
vlint --cache --rebaseline
vlint --cache --css
vlint --cache --css --rebaseline

Notes:

• vlint considers a file changed if the hash of its content is different
  • Metadata based caching is not planned
• If the version of the Nu Html Checker is different from the cache, every file will be validated even if it isn't changed

The cache is stored at .cache/@mitsue/vlint by default. You can change the cache location by specifying --cache-dir.

vlint --cache --cache-dir path/to/directory

Debug log files (debug-yyyymmdd-{html|css}-{pid}.log) are stored at .logs/@mitsue/vlint by default. You can change the location by specifying --logs-dir. This directory is separate from the cache, so caching .cache/ in CI does not pick up log files.

vlint --logs-dir path/to/directory

On non-zero exit, the debug log is kept and its absolute path is printed to stderr. On successful exit, the log file is deleted. Configure your CI artifacts settings so that these log files are collected as needed (for example, artifacts: when: on_failure with paths: [.logs/@mitsue/vlint/debug-*.log]).

Ignoring errors and warnings

vlint ignores errors and warnings defined in .vlintignore.yml.

You can generate or update the entirety of .vlintignore.yml by running the following commands:

vlint --rebaseline
vlint --css --rebaseline

Note: the above-mentioned commands remove comments from and sort keys (file paths) of .vlintignore.yml.

Also, you can update the specific parts of .vlintignore.yml by running the following commands:

vlint --update path/to/html
vlint --css --update path/to/css

Note: the above-mentioned commands remove comments from and sort keys (file paths) of .vlintignore.yml.

Additionally, you can edit .vlintignore.yml manually.

html:
    # glob pattern
    '**/*.html':
        # regular expression
        - 'Legacy encoding “.*” used\. Documents must use UTF-8\.'
        - 'The only allowed value for the “charset” attribute for the “meta” element is “utf-8”\.'
css:
    # glob pattern
    path_to_css/styles.css:
        # regular expression
        - 'Warning: Document uses the Unicode Private Use Area\(s\), which should not be used in publicly exchanged documents\. \(Charmod C073\)'

Changelog

0.13.0 - 2026-08-25

• Added debug log files for troubleshooting
• Retry once when Nu Html Checker requests fail with errors such as ECONNABORTED
• Made ignore path matching faster

0.12.1 - 2026-06-19

• Fixed an issue where vlint terminates when an HTTP request to Nu Html Checker fails

0.12.0 - 2026-05-18

• Correctly update caches when charset is defined
• Made default timeout be 30,000 milliseconds for HTML

0.11.3 - 2024-05-21

• Made default timeout be 120,000 milliseconds for CSS

0.11.2 - 2024-05-21

• Made default timeout be 30,000 milliseconds for CSS
• Use synchronous file system operations to improve performance, though the performance gain is unnoticeable in most cases

0.11.1 - 2024-04-01

• Made default timeout be 5,000 milliseconds
• Fixed various issues preventing W3C Markup Validator from validating files

0.11.0 - 2024-04-01

• Dropped support for Node.js below 18
• Replaced node-fetch with Node.js's fetch
• Added timeout option (default value is 1,000 milliseconds)
• Made messages translatable (English and Japanese are supported)
• Glob pattern should always use / as a path separator

0.10.0 - 2023-10-24

• vlint --rebaseline and vlint --update sort keys (file paths) of .vlintignore.yml

0.10.0-beta.0 - 2023-01-12

• Added cache feature
• Made vlint throw when unknown command line arguments were supplied
• Updated dependencies

0.9.1 - 2022-10-26

• Fixed error message format

0.9.0 - 2022-10-26

• Made vlint reject invalid config files (.vlintrc.yml and .vlintignore.yml)
• Made vlint reject invalid validation messages from Nu Html Checker and W3C Markup Validator
• Made vlint throw when there are unused messages in .vlintignore.yml
• Updated dependencies

0.8.1 - 2022-01-01

• Made README.md use example.com in config examples
• Updated dependencies

0.8.0 - 2021-09-06

• Made filtering faster
• Dropped Node.js 10 support
• Added ability to display the number of files to be validated
• Updated dependencies

0.7.0 - 2021-04-22

• Restored Node.js 10 support
• Fixed an issue that vlint escaped RegExp literals incorrectly
• Replaced meow with cac to reduce package install size
• Updated dependencies

0.6.1 - 2020-04-03

• Fixed wrong calculation of basic authorization credentials
• Updated dependencies

0.6.0 - 2020-04-01

• Added basic authorization support
• Updated dependencies

0.5.0 - 2020-02-25

• Switched from request to node-fetch
• Updated dependencies

0.4.1 - 2020-01-31

• Removed test coverage information from npm package

0.4.0 - 2020-01-31

• Added --update flag to support updating the specific part of .vlintignore.yml
• Added support for the '.yml' extension for '.vlintrc' and '.vlintignore' (.vlintrc.yml and .vlintignore.yml)
• Updated dependencies

0.3.0 - 2019-09-27

• Escape more regexp meta characters
• Fixed removing used patterns in .vlintignore.yaml

0.2.0 - 2019-09-21

• Respect ignore option in pre-commit hook scenario
• Updated dependencies

0.1.0 - 2019-08-08

• Initial release