The Nu Html Checker (vnu)

With the Nu Html Checker (vnu), you can:

Usage

You can run the vnu checker with one of the invocations from the vnu manual page. For example:

java -jar ~/vnu.jar [OPTIONS]... FILES|DIRECTORY|URL...

The OPTIONS section of the vnu manual page has details on all available options.

Releases

[!IMPORTANT] The release named “latest” is “production-ready” and is the only release you want to use. This project no longer does “major” version-numbered releases. Release 20.6.30 (30 June 2020) was the final such release.

Sources

The vnu source code is available on GitHub, as are instructions on how to build, test, and run the code.

Binaries and packages

The Nu Html Checker (vnu) is released upstream in these formats:

[!NOTE] The vnu.jar and vnu.war files require you to have Java 11 or above installed. The pre-compiled Linux, Windows, and macOS binaries don’t require you to have any version of Java already installed at all.

A Dockerfile (see Pulling the Docker image below) and npm, pip, and brew packages are also available.

You can get the latest release or run one of the following:

…and see the Usage and Web-based checking sections here. Or automate your checking with a frontend such as:

Web-based checking

The Nu Html Checker (vnu) — along with being usable as a standalone command-line client — can be run as an HTTP service, similar to validator.w3.org/nu, for browser-based checking of HTML documents, CSS stylesheets, and SVG images over the Web. To that end, the vnu checker is released as several separate packages:

All deployments expose a REST API that enables checking of HTML documents, CSS stylesheets, and SVG images from other clients, not just web browsers. And the Linux, Windows, and macOS binaries and vnu.jar package also include a simple HTTP client that enables you to either send documents to a locally-running instance of the vnu checker HTTP service — for fast command-line checking — or to any remote instance of the vnu checker HTTP service running anywhere on the Web.

The latest releases of the Linux, Windows, and macOS binaries and vnu.jar and vnu.war packages are available from the validator project at github. The following are detailed instructions on using them.

[!NOTE] Throughout these instructions, replace ~/vnu.jar with the actual path to that jar file on your system, and replace vnu-runtime-image/bin/java and vnu-runtime-image\bin\java.exe with the actual path to the vnu java or java.exe program on your system — or if you add the vnu-runtime-image/bin or vnu-runtime-image\bin directory your system PATH environment variable, you can invoke the vnu checker with just java nu.validator.servlet.Main 8888.

Standalone web server

See vnu-server for invocation manual page.

Servlet container

To run the vnu checker inside of an existing servlet container such as Apache Tomcat you will need to deploy the vnu.war file to that server following its documentation. For example, on Apache Tomcat you could do this using the Manager application or simply by copying the file to the webapps directory (since that is the default appBase setting). Typically you would see a message similar to the following in the catalina.out log file.

May 7, 2014 4:42:04 PM org.apache.catalina.startup.HostConfig deployWAR
INFO: Deploying web application archive /var/lib/tomcat7/webapps/vnu.war

Assuming your servlet container is configured to receive HTTP requests sent to localhost on port 80 and the context root of this application is vnu (often the default behavior is to use the WAR file’s filename as the context root unless one is explicitly specified) you should be able to access the application by connecting to http://localhost/vnu/.

[!NOTE] You may want to customize the /WEB-INF/web.xml file inside the WAR file (you can use any ZIP-handling program) to modify the servlet filter configuration. For example, if you wanted to disable the inbound-size-limit filter, you could comment out that filter like this:

<!--
  <filter>
      <filter-name>inbound-size-limit-filter</filter-name>
      <filter-class>nu.validator.servlet.InboundSizeLimitFilter</filter-class>
  </filter>
  <filter-mapping>
      <filter-name>inbound-size-limit-filter</filter-name>
      <url-pattern>/*</url-pattern>
  </filter-mapping>
-->

HTTP client (for fast command-line checking)

The vnu checker is packaged with an HTTP client you can use from the command line to either send documents to a locally-running instance of the vnu checker HTTP service — for fast command-line checking — or to a remote instance anywhere on the Web.

To check documents locally using the packaged HTTP client, do this:

  1. Start up the vnu checker as a local HTTP service, as described in the Standalone web server section.

  2. Invoke the HTTP client like from the commandline according to vnu-client manual page.

Pulling the Docker image

You can pull the vnu Docker image from https://ghcr.io/validator/validator in the GitHub container registry.

To pull and run the latest version of the vnu checker:

  docker run -it --rm -p 8888:8888 ghcr.io/validator/validator:latest

To pull and run a specific tag/version of the vnu checker from the container registry — for example, the 17.11.1 version:

  docker run -it --rm -p 8888:8888 ghcr.io/validator/validator:17.11.1

To bind the vnu checker to a specific address (rather than have it listening on all interfaces):

  docker run -it --rm -p 128.30.52.73:8888:8888 ghcr.io/validator/validator:latest

To make the vnu checker run with a connection timeout and socket timeout different from the default 5 seconds, use the CONNECTION_TIMEOUT_SECONDS and SOCKET_TIMEOUT_SECONDS environment variables:

  docker run -it --rm \
     -e CONNECTION_TIMEOUT_SECONDS=15 \
     -e SOCKET_TIMEOUT_SECONDS=15 \
     -p 8888:8888 \
     validator/validator

To make the vnu checker run with particular Java system properties set, use the JAVA_TOOL_OPTIONS environment variable:

  docker run -it --rm \
     -e JAVA_TOOL_OPTIONS=-Dnu.validator.client.asciiquotes=yes  \
     -p 8888:8888 \
     validator/validator

To define a service named vnu for use with docker compose, create a Compose file named docker-compose.yml (for example), with contents such as the following:

  version: '2' services:
    vnu:
      image: validator/validator ports:
        - "8888:8888"
      network_mode: "host" #so "localhost" refers to the host machine.

To run the vnu command-line checker provided by a Docker image on all the HTML files in the /var/www/html directory:

  docker run --rm -v /var/www/html:/data ghcr.io/validator/validator:latest vnu --skip-non-html /data

Build instructions

Follow the steps below to build, test, and run the vnu checker such that you can open http://0.0.0.0:8888/ in a Web browser to use the vnu checker Web UI.

  1. Make sure you have git, python, a 64-bit JDK 11 or above, and ant installed.

  2. Set the JAVA_HOME environment variable:

    export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64

export JAVA_HOME=$(/usr/libexec/java_home)            <-- macOS

  3. Create a working directory:

    git clone https://github.com/validator/validator.git

  4. Change into your working directory:

    cd validator

  5. Start the checker.py Python script:

    python ./checker.py all

The first time you run the checker.py Python script, you’ll need to be online and the build will need time to download several megabytes of dependencies.

Alternatively, if you wish to first download all dependencies, and build later when offline:

  1. Use the dldeps task to download

     python ./checker.py dldeps

  2. For all operations when offline, use the --offline option (place it before the task name)

     python ./checker.py --offline all

The steps above will build, test, and run the vnu checker such that you can open http://0.0.0.0:8888/ in a Web browser to use the vnu checker Web UI.

[!WARNING] Future checker releases will bind by default to the address 127.0.0.1. Your checker deployment might become unreachable unless you use the --bind-address option to bind to a different address:

python ./checker.py --bind-address=128.30.52.73 all

Use python ./checker.py --help to see command-line options for controlling the behavior of the script, as well as build-target names you can call separately; e.g.:

python ./checker.py build       # to build only

python ./checker.py build test  # to build and test

python ./checker.py run         # to run only

python ./checker.py jar         # to compile vnu.jar

Embedded Java usage

Maven:

<dependency>
    <groupId>nu.validator</groupId>
    <artifactId>validator</artifactId>
    <version>NN.NN.NN</version>
    <scope>test</scope>
</dependency>

Gradle:

testImplementation 'nu.validator:validator:NN.NN.NN'

Basic usage java code:

String html = ...
EmbeddedValidator validator = new EmbeddedValidator();
validator.setOutputFormat( EmbeddedValidator.OutputFormat.GNU );
try {
    String output = validator.validate( new ByteArrayInputStream( html.getBytes( StandardCharsets.UTF_8 ) ) );
    if (!output.isEmpty())
        throw new Exception( output ); //validation failed
} catch (SAXException e) {
    throw new Exception( "Cannot validate html", e );
}

Using a different output format requires the code to be adjusted.

Additional documentation

Additional documentation is available on the vnu wiki.

× For an integrated ToC on mobile, use
https://github.com/validator/validator/blob/main/README.md