plugins {
id 'org.aim42.htmlSanityCheck' version '2.0.0-rc2' (1)
}
HSC Gradle Plugin
The Gradle plugin of HTML Sanity Check (HSC) enables to check generated or native HTML documentation from the Gradle build.
Installation (Gradle Plugin)
Default Installation
Use the following snippet inside a Gradle build file:
1 | Checkout current version |
Legacy Installation
In the case of legacy plugin usage
buildscript {
repositories {
// maven { url "https://jitpack.io/" } (1)
mavenCentral() (2)
gradlePluginPortal() (3)
}
dependencies {
classpath ('gradle.plugin.org.aim42:htmlSanityCheck:2.0.0-rc2') (4)
}
}
apply plugin: 'org.aim42.htmlSanityCheck'
1 | In case you would like to use a development version (or even branch), check out development versions. |
2 | Beginning with version 2.x all releases will be published to Maven Central. |
3 | The Gradle Plugin Portal contains most versions or will redirect downloads of newer versions to Maven Central. |
4 | Check out the current version. |
Latest (development) versions
|
Usage
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
|
||
httpWarningCodes (optional)
|
Additional HTTP response codes treated as warning. Type: List. Default:
|
||
httpErrorCodes (optional)
|
Additional HTTP response codes treated as error. Type: List. Default:
|
||
httpSuccessCodes (optional)
|
Additional HTTP response codes treated as success. Type: List. Default:
|
Examples
Small Example
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
}
Extended example
build.gradle
import org.aim42.htmlsanitycheck.check.*
buildscript {
repositories {
mavenCentral()
// This is only necessary for older releases (< 2.00)
gradlePluginPortal()
}
}
plugins {
id 'org.aim42.htmlsanitycheck' version '2.0.0-rc2'
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]
}
Compatibility
The Plugin has been tested with the following Gradle versions:
// Test execution in CI will execute all versions.
// Local test is restricted to latest version
// 6.x or older does not work!
'7.6.3', // latest 7.x
'8.0.2', '8.1.1', '8.2.1', '8.3', '8.4',
'8.5', '8.6', '8.7', '8.8', '8.9',
'8.10.2' // all 8.x minor versions (latest patch release)
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
|
Development versions
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 "https://jitpack.io/" }
}
}
Then you can use a respective version in your build.gradle
:
plugins {
id 'org.aim42.htmlSanityCheck' version 'develop-SNAPSHOT'
}
JitPack builds
Building the desired version for the first time (or after some cache expiry at JitPack), you may experience a timeout. You can look up the current build state: |
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.