Repository files navigation

The Nu Html Checker (v.Nu) helps youcatch unintended mistakes in your HTML,CSS, and SVG. It enables you tobatch-check documents from the commandline and from other scripts/apps, and todeploy your own instance of thechecker as a service (likevalidator.w3.org/nu). Itssource code isavailable, as areinstructions on how to build, test, and run thecode.

ADockerfile (seePulling the Docker image below) andnpm,pip, andbrew packages are also available.

It is released upstream in these formats:

• pre-compiled Linux, Windows, and macOS binaries that include an embeddedJava runtime

• vnu.jar — a portable version you can use on any system that has Java 11 orabove installed

• vnu.war — fordeploying the checker service through a servlet containersuch as Tomcat

Note: Thevnu.jar andvnu.war files require you to have Java 11 or aboveinstalled. The pre-compiled Linux, Windows, and macOS binaries don’t require youto have any version of Java already installed at all.

You canget the latest release or rundocker run -it --rm -p 8888:8888 ghcr.io/validator/validator:latest,npm install vnu-jar,npm install --registry=https://npm.pkg.github.com @validator/vnu-jar,brew install vnu, orpip install html5validator and see theUsage andWeb-based checking sections below. Or automate your documentchecking with a frontend such as:

• Grunt plugin for HTML validation orGulp plugin for HTMLvalidation orMaven plugin for HTML validation

• html5validatorpip package (for integration in Travis CI, CircleCI,CodeShip, Jekyll, Pelican, etc.)

• LMVTFY: Let Me Validate That For You (auto-check JSFiddle/JSBin, etc.,links in GitHub issue comments)

Run the checker with one of the following invocations:

•vnu-runtime-image/bin/vnu OPTIONS FILES (Linux or macOS)

•vnu-runtime-image\bin\vnu.bat OPTIONS FILES (Windows)

•java -jar ~/vnu.jar OPTIONS FILES (any system with Java8+ installed)

…whereFILES are the documents to check, andOPTIONS are zero or more ofthe following options:

--errors-only --Werror --exit-zero-always --stdout --asciiquotes--user-agent USER_AGENT --no-langdetect --no-stream --filterfile FILENAME--filterpattern PATTERN --css --skip-non-css --also-check-css --svg--skip-non-svg --also-check-svg --xml --html --skip-non-html--format gnu|xml|json|text --help --verbose --version

TheOptions section below provides details on each option, and the rest ofthis section provides some specific examples.

Note: Throughout these examples, replace~/vnu.jar with the actual path tothat jar file on your system, and replacevnu-runtime-image/bin/vnu andvnu-runtime-image\bin\vnu.bat with the actual path to thevnu orvnu.batprogram on your system — or if you add thevnu-runtime-image/bin orvnu-runtime-image\bin directory your systemPATH environment variable, youcan invoke the checker with justvnu.

To check one or more documents from the command line:

  vnu-runtime-image/bin/vnu      FILE.html FILE2.html FILE3.html...  vnu-runtime-image\bin\vnu.bat  FILE.html FILE2.html FILE3.html...  java -jar ~/vnu.jar            FILE.html FILE2.html FILE3.html...

Note: If you get aStackOverflowError error when invoking the checker, tryadjusting the thread stack size by providing the-Xss option to java:

  java -Xss512k -jar ~/vnu.jar ...  vnu-runtime-image/bin/java -Xss512k \      -m vnu/nu.validator.client.SimpleCommandLineValidator ...

To check all documents in a particular directoryDIRECTORY_PATH as HTML:

  java -jar ~/vnu.jar            DIRECTORY_PATH  vnu-runtime-image/bin/vnu      DIRECTORY_PATH  vnu-runtime-image\bin\vnu.bat  DIRECTORY_PATH

Note: The examples in this section assume you have thevnu-runtime-image/bin orvnu-runtime-image\bin directory in your systemPATH environment variable. If you’re using the jar file instead, replacevnuin the examples withjava -jar ~/vnu.jar.

To check all documents in a particular directoryDIRECTORY_PATH as HTML, butskip any documents whose names don’t end with the extensions.html,.htm,.xhtml, or.xht:

  vnu --skip-non-html DIRECTORY_PATH

To check all documents in a particular directory as CSS:

  vnu --css DIRECTORY_PATH

To check all documents in a particular directory as CSS, but skip any documentswhose names don’t end with the extension.css:

  vnu --skip-non-css DIRECTORY_PATH

To check all documents in a particular directory, with documents whose names endin the extension.css being checked as CSS, and all other documents beingchecked as HTML:

  vnu --also-check-css DIRECTORY_PATH

To check all documents in a particular directory as SVG:

  vnu --svg DIRECTORY_PATH

To check all documents in a particular directory as SVG, but skip any documentswhose names don’t end with the extension.svg:

  vnu --skip-non-svg DIRECTORY_PATH

To check all documents in a particular directory, with documents whose names endin the extension.svg being checked as SVG, and all other documents beingchecked as HTML:

  vnu --also-check-svg DIRECTORY_PATH

To check a Web document:

  vnu _URL_  example: vnu http://example.com/foo

To check standard input:

  vnu -  example:  echo '<!doctype html><title>...' | vnu -  echo '<!doctype html><title>...' | java -jar ~/vnu.jar -

When used from the command line as described in this section, the checkerprovides the following options:

Specifies whether ASCII quotation marks are substituted for Unicode smartquotation marks in messages.default: [unset; Unicode smart quotation marks are used in messages]

Specifies that only error-level messages and non-document-error messages arereported (so that warnings and info messages are not reported).default: [unset; all messages reported, including warnings & info messages]

Makes the checker exit non-zero if any warnings are encountered (even ifthere are no errors).default: [unset; checker exits zero if only warnings are encountered]

Makes the checker exit zero even if errors are reported for any documents.default: [unset; checker exits 1 if errors are reported for any documents]

Makes the checker report errors and warnings to stdout rather than stderr.default: [unset; checker reports errors and warnings to stderr]

Specifies a filename. Each line of the file contains either a regularexpression or starts with "#" to indicate the line is a comment. Any errormessage or warning message that matches a regular expression in the file isfiltered out (dropped/suppressed).default: [unset; checker does no message filtering]

Specifies a regular expression. Any error message or warning message thatmatches the regular expression is filtered out (dropped/suppressed).As with all other checker options, this option may only be specified once.So to filter multiple error messages or warning messages, you must provide asingle regular expression that will match all the messages. The typical wayto do that for regular expressions is to OR multiple patterns together usingthe "|" character.default: [unset; checker does no message filtering]

Specifies the output format for reporting the results.default: "gnu"possible values: "gnu", "xml", "json", "text" [see information at URL below]https://github.com/validator/validator/wiki/Service-%C2%BB-Common-params#out

Shows detailed usage information.

Check documents as CSS but skip documents that don’t have *.css extensions.default: [unset; all documents found are checked]

Force all documents to be checked as CSS, regardless of extension.default: [unset]

Check documents as SVG but skip documents that don’t have *.svg extensions.default: [unset; all documents found are checked]

Force all documents to be checked as SVG, regardless of extension.default: [unset]

Skip documents that don’t have *.html, *.htm, *.xhtml, or *.xht extensions.default: [unset; all documents found are checked, regardless of extension]

Forces any *.xhtml or *.xht documents to be parsed using the HTML parser.default: [unset; XML parser is used for *.xhtml and *.xht documents]

Forces any *.html documents to be parsed using the XML parser.default: [unset; HTML parser is used for *.html documents]

Check CSS documents (in addition to checking HTML documents).default: [unset; no documents are checked as CSS]

Check SVG documents (in addition to checking HTML documents).default: [unset; no documents are checked as SVG]

Specifies the value of the User-Agent request header to send when checkingHTTPS/HTTP URLs.default: "Validator.nu/LV"

Disables language detection, so that documents are not checked for missingor mislabeled html[lang] attributes.default: [unset; language detection & html[lang] checking are performed]

Forces all documents to be be parsed in buffered mode instead of streamingmode (causes some parse errors to be treated as non-fatal document errorsinstead of as fatal document errors).default: [unset; non-streamable parse errors cause fatal document errors]

Specifies "verbose" output. (Currently this just means that the names offiles being checked are written to stdout.)default: [unset; output is not verbose]

Shows the checker version number.

The Nu Html Checker — along with being usable asa standalone command-lineclient — can be run as an HTTP service, similar tovalidator.w3.org/nu, for browser-based checking of HTML documents, CSSstylesheets, and SVG images over the Web. To that end, the checker is releasedas several separate packages:

• Linux, Windows, and macOS binaries for deploying the checker as a simpleself-contained service on any system

• vnu.jar for deploying the checker as a simple self-contained service on asystem with Java installed

• vnu.war for deploying the checker to a servlet container such as Tomcat

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

Thelatest releases of the Linux, Windows, and macOS binaries and vnu.jar andvnu.war packages are available from thevalidator project at github. Thefollowing are detailed instructions on using them.

Note: Throughout these instructions, replace~/vnu.jar with the actualpath to that jar file on your system, and replacevnu-runtime-image/bin/javaandvnu-runtime-image\bin\java.exe with the actual path to the checkerjavaorjava.exe program on your system — or if you add thevnu-runtime-image/binorvnu-runtime-image\bin directory your systemPATH environment variable,you can invoke the checker with justjava nu.validator.servlet.Main 8888.

To run the checker as a standalone service (using a built-in Jetty server), opena new terminal window and invoke the checker like this:

java -cp ~/vnu.jar              nu.validator.servlet.Main 8888vnu-runtime-image/bin/java      nu.validator.servlet.Main 8888vnu-runtime-image\bin\java.exe  nu.validator.servlet.Main 8888

Then openhttp://0.0.0.0:8888 in a browser. (To listen on a differentport, replace8888 with the port number.)

Warning: Future checker releases will bind by default to the address127.0.0.1. Your checker deployment might become unreachable unless you use thenu.validator.servlet.bind-address system property to bind the checker to adifferent address:

java -cp ~/vnu.jar \    -Dnu.validator.servlet.bind-address=128.30.52.73 \    nu.validator.servlet.Main 8888vnu-runtime-image/bin/java \    -Dnu.validator.servlet.bind-address=128.30.52.73 \    nu.validator.servlet.Main 8888vnu-runtime-image\bin\java.exe  \    -Dnu.validator.servlet.bind-address=128.30.52.73 \    nu.validator.servlet.Main 8888

When you openhttp://0.0.0.0:8888 (or whatever URL corresponds to thenu.validator.servlet.bind-address value you’re using), you’ll see a formsimilar tovalidator.w3.org/nu that allows you to enter the URL of an HTMLdocument, CSS stylesheet, or SVG image, and have the results of checking thatresource displayed in the browser.

Note: If you get aStackOverflowError error when using the checker, tryadjusting the thread stack size by providing the-Xss option to java:

  java -Xss512k -cp ~/vnu.jar nu.validator.servlet.Main 8888  vnu-runtime-image/bin/java -Xss512k -m vnu/nu.validator.servlet.Main 8888

To run the checker inside of an existing servlet container such as Apache Tomcatyou will need to deploy thevnu.war file to that server following itsdocumentation. For example, on Apache Tomcat you could do this using theManager application or simply by copying the file to thewebappsdirectory (since that is the defaultappBase setting). Typically you would seea message similar to the following in thecatalina.out log file.

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

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

Note: You may want to customize the/WEB-INF/web.xml file inside the WARfile (you can use any ZIP-handling program) to modify the servlet filterconfiguration. For example, if you wanted to disable the inbound-size-limitfilter, 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>-->

The checker is packaged with an HTTP client you can use from the command line toeither send documents to a locally-running instance of the 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 checker as a local HTTP service, as described in theStandalone web server section.

2. Open a new terminal window and invoke the HTTP client like this:

java -cp ~/vnu.jar nu.validator.client.HttpClient FILE.html...vnu-runtime-image/bin/java nu.validator.client.HttpClient FILE.html...

To send documents to an instance of the checker on the Web, such ashtml5.validator.nu/, use the nu.validator.client.host andnu.validator.client.port options, like this:

java -cp ~/vnu.jar -Dnu.validator.client.port=80 \    -Dnu.validator.client.host=html5.validator.nu \    nu.validator.client.HttpClient FILE.html...

…or like this:

vnu-runtime-image/bin/java -Dnu.validator.client.port=80 \    -Dnu.validator.client.host=html5.validator.nu \    nu.validator.client.HttpClient FILE.html...

Other options are documented below.

When using the packaged HTTP client for sending documents to an instance of thechecker HTTP service for checking, you can set Java system properties to controlconfiguration options for the checker behavior.

For example, you can suppress warning-level messages and only show error-levelones by setting the value of thenu.validator.client.level system property toerror, like this:

java -Dnu.validator.client.level=error \       -cp ~/vnu.jar nu.validator.client.HttpClient FILE.html...

…or like this:

vnu-runtime-image/bin/java -Dnu.validator.client.level=error \       -cp ~/vnu.jar nu.validator.client.HttpClient FILE.html...

Most of the properties listed below map to the common input parameters for thechecker service, as documented atgithub.com/validator/validator/wiki/Service-»-Common-params.

Specifies the hostname of the checker for the client to connect to.default: "127.0.0.1"

Specifies the hostname of the checker for the client to connect to.default: "8888"example: java -Dnu.validator.client.port=8080 -jar ~/vnu.jar FILE.html

Specifies the severity level of messages to report; to suppresswarning-level messages, and only show error-level ones, set this property to"error".default: [unset]possible values: "error"example: java -Dnu.validator.client.level=error -jar ~/vnu.jar FILE.html

Specifies which parser to use.default: "html"; or, for *.xhtml input files, "xml"possible values: [see information at URL below]https://github.com/validator/validator/wiki/Service-%C2%BB-Common-params#parser

Specifies the encoding of the input document.default: [unset]

Specifies the content-type of the input document.default: "text/html"; or, for *.xhtml files, "application/xhtml+xml"

Specifies the output format for messages.default: "gnu"possible values: [see information at URL below]https://github.com/validator/validator/wiki/Service-%C2%BB-Common-params#out

Specifies whether ASCII quotation marks are substituted for Unicode smartquotation marks in messages.default: "yes"possible values: "yes" or "no"

Binds the validator service to the specified IP address.default: 0.0.0.0 [causes the checker to listen on all interfaces]possible values: The IP address of any network interfaceexample: -Dnu.validator.servlet.bind-address=127.0.0.1

Specifies the connection timeout.default: 5000possible values: number of millisecondsexample: -Dnu.validator.servlet.connection-timeout=5000

Specifies the socket timeout.default: 5000possible values: number of millisecondsexample: -Dnu.validator.servlet.socket-timeout=5000

You can pull the checker Docker image fromhttps://ghcr.io/validator/validator in the GitHub container registry.

To pull and run the latest version of the checker:

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

To pull and run a specific tag/version of the checker from the containerregistry — for example, the17.11.1 version:

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

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

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

To make the checker run with a connection timeout and socket timeout differentthan the default 5 seconds, use theCONNECTION_TIMEOUT_SECONDS andSOCKET_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 checker run with particular Java system properties set, use theJAVA_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 namedvnu for use withdocker compose, create a Composefile nameddocker-compose.yml (for example), with contents such as thefollowing:

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

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

1. Make sure you have git, python, and JDK 8 or above installed.

2. Set theJAVA_HOME environment variable:

   export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64 <-- Ubuntu, etc.

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

3. Create a working directory:

   git clonehttps://github.com/validator/validator.git

4. Change into your working directory:

   cd validator

5. Start the checker Python script:

   python ./checker.py all

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

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

Warning: Future checker releases will bind by default to the address127.0.0.1. Your checker deployment might become unreachable unless you use the--bind-address option to bind the checker to a different address:

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

Usepython ./checker.py --help to see command-line options for controlling thebehavior 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

• python ./checker.py update-shallow &&
    python ./checker.py dldeps &&
    python ./checker.py jar       # to compile vnu.jar faster