Html Sanity Check Consumer

A demo for the htmlSanityCheck Gradle plugin.

Contains a few asciidoc files to show typical semantic errors in html files which HtmlSC checker will detect and report.

Table of Contents

• Usage
  • Files Containing Typical Errors
• Types of Errors Checked by htmlSC
  • Missing Images
  • Broken Cross References
  • Missing Local Resources
  • Broken External Links
  • Ambiguous Link Targets
  • Broken ImageMaps
  • Missing Alt-Attributes (in Image-Tags)
• Stats

Usage

Checkout from Github, then invoke the following commands:

gradle htmlSanityCheck

Gradle will download all required libraries, compile the asciidoctor source files into html and invoke the HtmlSC. You’ll find the checking results in

build/reports/htmlchecks/index.html

Files Containing Typical Errors

The following file contains loads of semantic errors:

 ./src/asciidoc/many-errors.adoc

Another file is provided, error-free:

 ./src/asciidoc/no-errors.adoc

Types of Errors Checked by htmlSC

• ✓ Missing Images

• ✓ Broken Cross References

• ✓ Missing Local Resources

• ❏ Broken External Links

• ✓ Ambiguous Link Targets

• ❏ Broken Image Maps

• ✓ Missing Alt-Attribute in Image Tags

Missing Images

More precisely, htmlSC looks for missing image files on the local file system, as it currently does NOT support checking of external resources.

Broken Cross References

(synonym: broken internal links)

Html anchor tags contain href attributes, which denote the link-target where the browser shall jump when the appropriate link is clicked.

Example:

<a href="missing">missing link</a>  // (1)

<h1 id="existing">Sample Header</h1> // (2)
<a href="existing"> jump to the sample header</a> //(3)

1. This link tells the browser to jump to a location with id="missing" (which is missing in this document…​)

2. The id=…​ attribute denotes a specific identification for an HTML element.

3. This `href`is an existing link target.

Missing Local Resources

TODO

Broken External Links

HtmlSC does currently not support external link checking. See issue #34

Ambiguous Link Targets

(synonym: duplicate ids)

If a link target (id-attribute) occures more than once, the browser cannot determine where to jump.

Example:

<a href="#dupeTarget">duplicate Target</a>  // (1)

<h2 id="dupeTarget">One Header</h2> // (2)
... some text

<h2 id="dupeTarget">Another Header</h2> // (3)
... some more text

1. a link with link-target 'dupeTarget'

2. One header with id 'dupeTarget'

3. Another header with the same id

Broken ImageMaps

ImageMaps allow parts of an image to be used as hyperlinks to arbitrary targets.

ImageMaps need two html tags to work: An <img…​> tag plus a <map…​> tag.

See the following example for a correct ImageMap (in html source)

<img src="image.jpg" usemap="#yourmap"> // (1)

<map name="yourmap"> // (2)
  <area shape="rect" coords="0,0,1,1" href="#test1"> // (3)
  <area shape="circle" coords="0,1,1" href="#test2">
</map>

1. an image (img-tag) with a "usemap" attribute.

2. the actual map, defining a number of click-sensitive

3. areas on the image together with the respective link targets.

Several things could go wrong with ImageMaps

1. referenced map does not exist (wrong usemap or wrong map-name)

2. several maps exists with same name (ambiguous map-name)

3. map not referenced (dangling map)

4. no link-targets in map (empty map)

5. link-target missing in area (empty href in area)

6. broken link targets in map (broken href in area-tag)

Missing Alt-Attributes (in Image-Tags)

If the browser cannot access or render an image it will display the alternative text given in the alt-attribute of image-tags.

<img src="image.jpg">

Stats

last update 2024-06-11, build with Asciidoctor 2.0.22