Skip to content

Latest commit

 

History

History
230 lines (161 loc) · 7.3 KB

index.adoc

File metadata and controls

230 lines (161 loc) · 7.3 KB
Raw

URLs

Tip
 Do you want to improve this page? Please git-edit it on GitHub.

Htmlchecker scans the .html files present in a given directory and verify that certain rules are violated or not. A report with all warnings and errors can be obtained as HTML or as XML file.

Checked rules

Following rules ensures that local files referenced as attribute of some html tags are present. Missing files correspond to an error.

Output report

The html report looks like this:

HTML Report

See an example for the git-site-example project: example-report.html.

The xml report looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<issues>
    <issue
        name="LOCAL_A_TAG_RULE"
        severity="Error"
        message="File &apos;page2.html&apos; (relative to &apos;index.html&apos;) ......"
        category="Local"
        summary="Local file should be present"
        explanation="All local files referenced by the `href` attribute ......"
        location="....../site-example/src/main/resources/site/index.html"
        lineNumber="15"
    />
    <!-- ..... -->
</issues>

See an example for the git-site-example project: example-report.xml.

Download

Since version 1.2.0, a compiled version of the project is available on maven central.

For the core library:

coordinates on maven central (xml notation)
<dependency>
  <groupId>{maven-group-id}</groupId>
  <artifactId>htmlchecker-core</artifactId>
  <version>{last-stable-version}</version>
</dependency>

An other interesting approach is to run the cli jar using Jbang to take care of the classpath:

jbang command to start the cli
jbang run {maven-group-id}:htmlchecker-cli:{last-stable-version} --help

A maven plugin and a gradle plugin are available as well.

Run the tool

As maven plugin

In the plugins section of your build section, you can add something like this:

Maven plugin usage example
link:../../site-example/pom.xml[role=include]

Possible configuration parameters for the maven plugin:

sourceDirectory

Directory to scan (default value is ${project.basedir}).

outputType

Type of report that should be created, possible values:

  • html (default)

  • xml

outputFile

Name of the file, where the report will be created (default value is ${project.build.directory}/report.html).

srcPathPrefix

Local or remote path to the source directory, if not set (default) a relative path to the local file will be computed. For the site-example project in this repository, the remote path to view the files on GitHub is: https://github.com/jmini/htmlchecker/blob/master/site-example/src/main/resources/site/.

enableOnlyRules

Only check for these rules. Ignored if not set (default).

disableRules

Disable the list of rules. Ignored if not set (default).

enableRules

Enable the list of rules. Ignored if not set (default).

enableCategories

Run all rules of certain categories. Ignored if not set (default).

noWarnings

Only check for errors; ignore warnings. Possible values:

  • false (default)

  • true

allWarnings

Check all warnings, including those off by default. Possible values:

  • false (default)

  • true

waringsAreErrors

Treat all warnings as errors. Possible values:

  • false (default)

  • true

From the command line

After having unzipped the archive, you can run htmlchecker.cmd or htmlchecker.sh depending on your operating system.

Run the command line tool example
htmlchecker --html myreport.html site-example/src/main/resources/site/

Here is the complete list of options:

Complete list of options for htmlchecker
link:../../htmlchecker-cli/src/test/resources/htmlchecker-help.txt[role=include]

Jenkins integration

With version 1.2.0 and newer a new export format is available: jenkins-xml The generated XML file can be parsed by Jenkins using the Warnings Next Generation Plugin (tested with version 5.3.0).

In your build configuration, in the "Post-build Actions" section, add a "Record compiler warnings and static analysis results" item:

Record compiler warnings and static analysis results configuration

Configure the item with following values:

  • Tool: Warnings Plugin Native Format

  • Report File Pattern: target/htmlchecker-report.xml (example value, must match with the output file created when you run the tool)

  • Custom ID: htmlchecker (optional)

  • Custom Name: HTML Checker (optional)

Here the same configuration as Jenkins pipeline script:

Jenkins pipeline syntax
recordIssues(tools: [issues(id: 'htmlchecker', name: 'HTML Checker', pattern: 'target/htmlchecker-report.xml')])

Source Code

The project is hosted on GitHub: {git-repository}

Build

This project is using gradle.

Command to build the sources locally:

./gradlew build

Command to deploy to your local maven repository:

./gradlew publishToMavenLocal

Command to build the documentation page:

./gradlew asciidoctor

The output of this command is an HTML page located at <git repo root>/build/docs/html5/index.html.

For project maintainers

signing.gnupg.keyName and signing.gnupg.passphrase are expected to be set in your local gradle.properties file to be able to sign. sonatypeUser and sonatypePassword are expected to be set in order to be able to publish to a distant repository.

Command to build and publish the result to maven central:

./gradlew publishToSonatype

Command to upload the documentation page on GitHub pages:

./gradlew gitPublishPush

Command to perform a release:

./gradlew release -Prelease.useAutomaticVersion=true

Using ssh-agent

Some tasks requires pushing into the distant git repository (release task or updating the gh-pages branch). If they are failing with errors like this:

org.eclipse.jgit.api.errors.TransportException: ... Permission denied (publickey).

Then ssh-agent can be used.

eval `ssh-agent -s`
ssh-add ~/.ssh/id_rsa

(source for this approach)