The {gradle-url}[Gradle] plugin of HTML Sanity Check (HSC) enables to check generated or native HTML documentation from the Gradle build.
Use the following snippet inside a Gradle build file:
plugins {
id 'org.aim42.{project}' version '{hsc-version}' // (1)
}-
Checkout current version
In the case of legacy plugin usage
buildscript {
repositories {
// maven { url "{jitpack-url}" } // (1)
mavenCentral() // (2)
gradlePluginPortal() // (3)
}
dependencies {
classpath ('gradle.plugin.org.aim42:{project}:{hsc-version}') // (4)
}
}
apply plugin: 'org.aim42.{project}'-
In case you would like to use a development version (or even branch), check out development versions.
-
Beginning with version
2.xall releases will be published to Maven Central. -
The Gradle Plugin Portal contains most versions or will redirect downloads of newer versions to Maven Central.
-
Check out the current version.
|
Important
|
Latest (development) versions
|
The plugin adds a new task named htmlSanityCheck.
This task exposes a few properties as part of its configuration:
sourceDir (mandatory)
|
Directory where the HTML files are located. Type: Directory. |
||
sourceDocuments (optional)
|
An override to process several source files, which may be a subset of all files available in Type: Default: All files in |
||
checkingResultsDir (optional)
|
Directory where the checking results written to. Type: Directory. Default: |
||
junitResultsDir (optional)
|
Directory where the results are written to in JUnit XML format. JUnit XML can be read by many tools, including CI environments. Type: Directory. Default: |
||
failOnErrors (optional)
|
Fail the build if any error was found in the checked pages. Type: Boolean. Default: |
||
httpConnectionTimeout (optional)
|
Timeout for http requests in ms. Type: Integer. Default: |
||
ignoreLocalHost (optional)
|
Ignore localhost as hostname. Type: Boolean. Default: |
||
ignoreIPAddresses (optional)
|
Ignore IP addresses as hostname. Type: Boolean. Default: |
||
checkerClasses (optional)
|
The set of checker classes to be executed. Type: List. Default: All available checker classes. Checker Classes
link:../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/check/AllCheckers.java[role=include] |
||
httpWarningCodes (optional)
|
Additional HTTP response codes treated as warning. Type: List. Default: link:../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/tools/Web.java[role=include]
// Redirects included
link:../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/tools/Web.java[role=include]
|
||
httpErrorCodes (optional)
|
Additional HTTP response codes treated as error. Type: List. Default: link:../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/tools/Web.java[role=include] |
||
httpSuccessCodes (optional)
|
Additional HTTP response codes treated as success. Type: List. Default: link:../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/tools/Web.java[role=include] |
build.gradle
apply plugin: 'org.aim42.htmlSanityCheck'
htmlSanityCheck {
sourceDir = file( "$buildDir/docs" )
// where to put results of sanityChecks...
checkingResultsDir = file( "$buildDir/report/htmlchecks" )
// fail build on errors?
failOnErrors = true
}build.gradleimport org.aim42.htmlsanitycheck.check.*
buildscript {
repositories {
mavenCentral()
// This is only necessary for older releases (< 2.00)
gradlePluginPortal()
}
}
plugins {
id 'org.aim42.htmlsanitycheck' version '{hsc-version}'
id 'org.asciidoctor.convert' version '1.5.8'
}
// ==== path definitions =====
// ===========================
// location of AsciiDoc files
def asciidocSrcPath = "$projectDir/src/asciidoc"
// location of images used in AsciiDoc documentation
def srcImagesPath = "$asciidocSrcPath/images"
// results of asciidoc compilation (HTML)
// (input for htmlSanityCheck)
// this is the default path for asciidoc-gradle-convert
def htmlOutputPath = "$buildDir/asciidoc/html5"
// images used by generated html
def targetImagesPath = htmlOutputPath + "/images"
// where HTMLSanityCheck checking results ares stored
def checkingResultsPath = "$buildDir/report/htmlchecks"
apply plugin: 'org.asciidoctor.convert'
asciidoctor {
sourceDir = new File( asciidocSrcPath )
options backends: ['html5'],
doctype: 'book',
icons: 'font',
sectlink: true,
sectanchors: true
resources {
from( srcImagesPath )
into targetImagesPath
}
}
apply plugin: 'org.aim42.htmlSanityCheck'
htmlSanityCheck {
// ensure asciidoctor->html runs first
// and images are copied to build directory
dependsOn asciidoctor
sourceDir = new File( htmlOutputPath )
// files to check, specified as a file tree with filtering
sourceDocuments = fileTree(sourceDir) {
include "many-errors.html", "no-errors.html"
}
// where to put results of sanityChecks...
checkingResultsDir = new File( checkingResultsPath )
// fail build on errors
failOnErrors = true
// http connection timeout in milliseconds
httpConnectionTimeout = 1000
// which statuscodes shall be interpreted as warning, error or success
// defaults to standard
httpWarningCodes = [401]
// httpErrorCodes
// httpSuccessCodes
// only execute a subset of all available checks
// available checker:
// * BrokenCrossReferencesChecker
// * BrokenHttpLinksChecker
// * DuplicateIdChecker
// * ImageMapChecker
// * MissingAltInImageTagsChecker
// * MissingImageFilesChecker
// * MissingLocalResourcesChecker
checkerClasses = [DuplicateIdChecker, MissingImageFilesChecker]
}The Plugin has been tested with the following Gradle versions:
link:src/test/groovy/org/aim42/htmlsanitycheck/gradle/HtmlSanityCheckTaskFunctionalSpec.groovy[role=include]|
Note
|
The full range of Gradle versions is only tested in CI (GitHub action). The local test only tests the latest Gradle version: Restricting versions to the latest versions locally
link:src/test/groovy/org/aim42/htmlsanitycheck/gradle/HtmlSanityCheckTaskFunctionalSpec.groovy[role=include] |
In case you want to use a current development (or arbitrary branch or tag) version from GitHub,
add the following to your settings.gradle:
pluginManagement {
repositories {
maven { url "{jitpack-url}" }
}
}Then you can use a respective version in your build.gradle:
plugins {
id 'org.aim42.{project}' version 'develop-SNAPSHOT'
}|
Note
|
JitPack builds
Building the desired version for the first time (or after some cache expiry at {jitpack-url}[JitPack]), you may experience a timeout. You can look up the current build state: 
|