This project provides some basic sanity checking on html files.
It can be helpful in case of html generated from e.g. Asciidoctor, Markdown or other formats - as converters usually don’t check for missing images or broken links.
It can be used as Gradle plugin. Standalone Java and graphical UI are planned for future releases.
Use the following snippet inside a Gradle build file:
plugins {
id 'org.aim42.htmlSanityCheck' version '0.9.7'
}OR
buildscript {
repositories {
maven {
url "https://plugins.gradle.org/m2/"
}
}
dependencies {
classpath ('gradle.plugin.org.aim42:htmlSanityCheck:0.9.7')
}
}
apply plugin: 'org.aim42.htmlSanityCheck'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: File. Default: |
| sourceDocuments |
(optional) an override to process several source files, which may be a subset of all
files available in |
| checkingResultsDir |
(optional) directory where the checking results written to.
Defaults to |
| junitResultsDir |
(optional) directory where the results written to in JUnit XML format. JUnit XML can be
read by many tools including CI environments.
Defaults to |
| failOnErrors |
(optional) if set to "true", the build will fail if any error was found in the checked pages.
Defaults to |
| checkExternalLinks |
(optional, planned) if set to "true", external references are checked too.
Defaults to |
apply plugin: 'org.aim42.htmlSanityCheck'
htmlSanityCheck {
sourceDir = new File( "$buildDir/docs" )
// files to check - in Set-notation
sourceDocuments = [ "one-file.html", "another-file.html", "index.html"]
// where to put results of sanityChecks...
checkingResultsDir = new File( "$buildDir/report/htmlchecks" )
checkExternalLinks = false
// fail build on errors?
failOnErrors = true
}buildscript {
repositories {
maven {
url "https://plugins.gradle.org/m2/"
}
jcenter()
}
dependencies {
classpath (group: 'gradle.plugin.org.aim42',
name: 'htmlSanityCheck',
version: '0.9.7')
classpath (group: 'org.asciidoctor',
name: 'asciidoctor-gradle-plugin',
version: '1.5.3')
}
}
// ==== 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, in Set-notation
sourceDocuments = [ "many-errors.html", "no-errors.html"]
// where to put results of sanityChecks...
checkingResultsDir = new File( checkingResultsPath )
// false: restrict checks to local resources
// true: also check external (e.g. http, https...) links.
checkExternalLinks = false
}The overall goal is to create neat and clear reports, showing evantual errors within HTML files - as shown in the adjoining figure. |
|
Finds all '<a href="XYZ">' where XYZ is not defined.
<a href="#missing>internal anchor</a>
...
<h2 id="missinG">Bookmark-Header</h2>In this example, the bookmark is misspelled.
Images, referenced in '<img src="XYZ"…' tags, refer to external files. The existence of these files is checked by the plugin.
If any is defined more than once, any anchor linking to it will be confused :-)
Image-tags should contain an alt-attribute that the browser displays when the original image file cannot be found or cannot be rendered. Having alt-attributes is good and defensive style.
In addition to checking HTML, this project serves as an example for arc42.
Please see our software architecture documentation.
This tiny piece rests on incredible groundwork:
-
Jsoup HTML parser and analysis toolkit - robust and easy-to-use.
-
IntelliJ IDEA - my (Gernot) best (programming) friend.
-
Of course, Groovy, Gradle, JUnit and Spockframework.
-
The plugin heavily relies on code provided by the Gradle project.
-
Inspiration on code organization, implementation and testing of the plugin came from the Asciidoctor-Gradle-Plugin by [@AAlmiray].
-
Code for string similarity calculation by Ralph Rice.
-
Initial implementation, maintenance and documentation by Gernot Starke.
Several sources provided help during development:
-
The code4reference tutorial an Gradle custom plugins, part 1 and part 2.
-
Of course, the JSoup API documentation
Please report issues or suggestions.
Want to improve the plugin: Fork our repository and send a pull request.
