# html5validator
**Repository Path**: mirrors_adamchainz/html5validator
## Basic Information
- **Project Name**: html5validator
- **Description**: Command line tool to validate HTML5 files. Great for continuous integration.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-12-31
- **Last Updated**: 2026-02-07
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
HTML5 Validator
===============
``html5validator`` is a command line tool that tests files for
HTML5 validity. This was written with static site generators like
`Jekyll `_ and
`Pelican `_ in mind. Dynamic html content
(for example from JS template engines) can be crawled
(e.g. with `localcrawl `_)
and then validated.
.. image:: https://github.com/svenkreiss/html5validator/actions/workflows/tests.yml/badge.svg?branch=main
:target: https://github.com/svenkreiss/html5validator/actions/workflows/tests.yml
.. image:: https://badge.fury.io/py/html5validator.svg
:target: https://pypi.python.org/pypi/html5validator/
Install
-------
This module requires Python 3.6, 3.7, 3.8 or 3.9 and Java 8 (``openjdk8`` or ``oraclejdk8``).
Install with ``pip install html5validator`` and run with
.. code-block:: bash
html5validator --root _build/
to validate all html files in the ``_build`` directory.
Run ``html5validator --help`` to see the list of command line options::
usage: html5validator [-h] [--root ROOT] [--match MATCH [MATCH ...]]
[--blacklist [BLACKLIST ...]] [--show-warnings]
[--no-langdetect] [--no-vnu-stdout] [--no-asciiquotes]
[--format {gnu,xml,json,text}]
[--ignore [IGNORE ...]] [--ignore-re [IGNORE_RE ...]]
[--config CONFIG] [-l] [-ll] [-lll] [--log LOG]
[--log-file LOG_FILE] [--version]
[files ...]
[v0.4.0] Command line tool for HTML5 validation. Return code is 0 for valid
HTML5. Arguments that are unknown to html5validator
are passed as arguments to `vnu.jar`.
positional arguments:
files specify files to check
optional arguments:
-h, --help show this help message and exit
--root ROOT start directory to search for files to validate
--match MATCH [MATCH ...]
match file pattern in search (default: "*.html" or
"*.html *.css" if --also-check-css is used)
--blacklist [BLACKLIST ...]
directory names to skip in search
--show-warnings show warnings and count them as errors
--no-langdetect disable language detection
--no-vnu-stdout do not use --stdout with vnu.jar
--no-asciiquotes do not use --asciiquotes with vnu.jar
--format {gnu,xml,json,text}
output format
--ignore [IGNORE ...]
ignore messages containing the given strings
--ignore-re [IGNORE_RE ...]
regular expression of messages to ignore
--config CONFIG Path to a config file for options
-l run on larger files: sets Java stack size to 2048k
-ll run on larger files: sets Java stack size to 8192k
-lll run on larger files: sets Java stack size to 32768k
--log LOG log level: DEBUG, INFO or WARNING (default: WARNING)
--log-file LOG_FILE Name for log file. If no name supplied then no log
file will be created
--version show program's version number and exit
This module uses the `validator.nu backend `_
which is written in Java. Therefore, a Java Runtime Environment must be
available on your system. Since version 0.2, Java 8 is required.
Checking CSS/SVG
----------------
.. code-block:: bash
html5validator --root _build/ --also-check-css
# checking only CSS
html5validator --root _build/ --skip-non-css
Replace ``css`` with ``svg`` for similar behavior with SVG files.
Integration with CircleCI 1.0
-----------------------------
Create a ``circle.yml`` file:
.. code-block:: yaml
machine:
java:
version: openjdk8
dependencies:
pre:
- sudo pip install html5validator
test:
override:
- html5validator --root _build/
in your repository with static html files and get HTML5 validation on every
``git push``.
Integration with CircleCI 2.0
-----------------------------
Simplified example ``circle.yml`` file from
`pelican-jsmath `_:
.. code-block:: yaml
version: 2
jobs:
test-3.6:
docker:
- image: python:3.6-stretch
steps:
- run:
name: install Java
command: apt-get update && apt-get install -y openjdk-8-jre
- checkout
- run:
name: install
command: pip install '.[test]'
- run:
name: generate html
working_directory: test/example_site
command: pelican content -s pelicanconf.py
- run:
name: validate html
command: html5validator --root test/example_site/output
workflows:
version: 2
build_and_test:
jobs:
- test-3.6
Integration with TravisCI
-------------------------
Create a ``.travis.yml`` file. This is an example for a Python project:
.. code-block:: yaml
language: python
python:
- "2.7"
addons:
apt:
packages:
- openjdk-8-jre # install Java8 as required by vnu.jar
branches:
only:
- gh-pages
install:
- pip install html5validator
script: html5validator --root _build/
This is an example for Java project:
.. code-block:: yaml
language: java
jdk:
- oraclejdk8 # vnu.jar requires Java 8
branches:
only:
- gh-pages
install:
- pip install --user html5validator
script: html5validator --root _build/
Fix the ``html5validator`` version by using
``pip install --user html5validator==``.
You can also use this for user pages (repositories of the form ``.github.io``)
where the html files are in the master branch. You only have to remove:
.. code-block:: yaml
branches:
only:
- gh-pages
from ``.travis.yml``. I am using this on
`my own user page `_.
Integration with CodeShip
-------------------------
Add this lines to the ``Setup Commands``:
.. code-block:: yaml
jdk_switcher use oraclejdk8
pip install html5validator
This is an example for Ruby project:
.. code-block:: yaml
rvm use 2.2.0 --install
bundle install
bundle update
export RAILS_ENV=test
jdk_switcher use oraclejdk8
pip install html5validator
Integration with GitLab CI
--------------------------------
There is a docker image available to be used with GitLab CI or stand alone.
`Docker image `_,
`Docker image repo `_.
Example for html test `(Full) `_:
.. code-block:: yaml
html_test:
stage: html_test
image: cyb3rjak3/html5validator:latest
script:
- html5validator --root public/ --also-check-css --format text
Integration with GitHub Actions
---------------------------------
There is a Github Action that can be used to check repositories. `Marketplace Link `_.
Example action:
.. code-block:: yaml
- name: HTML5 Validator
uses: Cyb3r-Jak3/html5validator-action@master
with:
root: html/
Technical Notes
---------------
* If you are using grunt already, maybe consider using the
`grunt-html `_ plugin for grunt instead.
* Use ``--ignore-re 'Attribute "ng-[a-z-]+" not allowed'`` with angular.js apps.
* Example with multiple ignores: ``html5validator --root tests/multiple_ignores/ --ignore-re 'Attribute "ng-[a-z-]+" not allowed' 'Start tag seen without seeing a doctype first'``
Changelog
---------
Install a particular version, for example ``0.1.14``, with ``pip install html5validator==0.1.14``.
* `main `_
* `0.4.0 `_ (2021-05-03)
* update vnu jar to 21.4.9
* use `--stdout` and `--asciiquotes` by default for vnu.jar
* make `--format=json` parsable
* better log file and config file tests
* move tests to GitHub Actions and setup auto-deploy to PyPI from GitHub releases
* `0.3.3 `_ (2019-12-07)
* `PR#59 `_
* `0.3.2 `_ (2019-11-22)
* update vnu jar to 18.11.5
* better output check `PR#57 `_ by `@Cyb3r-Jak3 `_
* `0.3.1 `_ (2018-06-01)
* update vnu jar to 18.3.0
* pass remaining command line options to ``vnu.jar``
* allow to match multiple file patterns, e.g. ``--match *.html *.css``
* `0.3.0 `_ (2018-01-21)
* update vnu jar to 17.11.1
* support explicit list of files: ``html5validator file1.html file2.html``
* new command line options: ``--no-langdetect``, ``--format``
* new tests for ``--show-warnings`` flag
* refactored internal API
* bugfix: check existence of Java
* bugfix: split Java and vnu.jar command line options
* `0.2.8 `_ (2017-09-08)
* update vnu jar to 17.9.0
* suppress a warning from the JDK about picked up environment variables
* `0.2.7 `_ (2017-04-09)
* update vnu jar to 17.3.0
* lint Python code
* `0.2.5 `_ (2016-07-30)
* clamp CLI return value at 255: `PR26 `_
* `0.2.4 `_ (2016-07-14)
* a fix for Cygwin thanks to this `PR20 `_
* `0.2.3 `_ (2016-07-05)
* ``vnu.jar`` updated to 16.6.29 thanks to this `PR `_
* `0.2.2 `_ (2016-04-30)
* ``vnu.jar`` updated to 16.3.3
* `0.2.1 `_ (2016-01-25)
* ``--ignore``, ``--ignore-re``: ignore messages containing an exact pattern or
matching a regular expression (migration from version 0.1.14: replace ``--ignore`` with ``--ignore-re``)
* curly quotes and straight quotes can now be used interchangeably
* change Java stack size handling (introduced the new command line options ``-l``, ``-ll`` and ``-lll``)
* update vnu.jar to 16.1.1 (which now requires Java 8)
* `0.1.14 `_ (2015-10-09)
* change text encoding handling
* adding command line arguments ``--log`` and ``--version``
* `0.1.12 `_ (2015-05-07)
* document how to specify multiple regular expressions to be ignored
* add ``--ignore`` as command line argument. Takes a regular expression
for warnings and errors that should be ignored.
* `0.1.9 `_ (2015-03-02)