= image:htmlsanitycheck-logo.png[hSC] Html Sanity Check Consumer :experimental: :linkattrs: :source-highlighter: pygments :toc: :toc-placement!:
image:http://img.shields.io/:license-ccsa4-green.svg[link="https://creativecommons.org/licenses/by-sa/4.0/"^] image:http://img.shields.io/github/issues/aim42/htmlsanitycheckConsumer.svg[link="https://github.com/aim42/htmlSanityCheckConsumer/issues"] image:https://badge.waffle.io/aim42/htmlSanityCheckConsumer.svg?label=bug&title=Bugs[Bugs]
A demo for the https://github.com/aim42/htmlSanityCheck[htmlSanityCheck] Gradle plugin.
Contains a few asciidoc files to show typical semantic errors in html files which kbd:[HtmlSC] checker will detect and report.
toc::[]
== Usage Checkout from Github, then invoke the following commands:
gradle htmlSanityCheckGradle will download all required libraries, compile the asciidoctor source files into html and invoke the kbd:[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 kbd:[htmlSC]
- [x] <<missing-images, Missing Images>>
- [x] <<broken-cross-references, Broken Cross References>>
- [x] <<missing-local-resources, Missing Local Resources>>
- [ ] Broken External Links
- [x] <<ambiguous-link-targets, Ambiguous Link Targets>>
- [ ] <<broken-image-maps, Broken Image Maps>>
- [x] <<missing-alt-attributes, Missing Alt-Attribute in Image Tags>>
[[missing-images]] === Missing Images More precisely, kbd:[htmlSC] looks for missing image files on the local file system, as it currently does NOT support checking of external resources.
[[broken-cross-references]] === Broken Cross References [small]#(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:
[source,html]
missing link // <1>
Sample Header
// <2> jump to the sample header //<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-resoures]] === Missing Local Resources TODO [[broken-external-links]] === Broken External Links kbd:[HtmlSC] does currently not support external link checking. See https://github.com/aim42/htmlSanityCheck/issues/34[issue #34] [[ambiguous-link-targets]] === Ambiguous Link Targets [small]#(synonym: duplicate ids)# If a link target (id-attribute) occures more than once, the browser cannot determine where to jump. Example: [source,html] ---- duplicate Target // <1>One Header
// <2> ... some textAnother Header
// <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-image-maps]] === Broken ImageMaps ImageMaps allow parts of an image to be used as hyperlinks to arbitrary targets. ImageMaps need two html tags to work: An `
// <1>
----
<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*
. referenced map does not exist (wrong usemap or wrong map-name)
. several maps exists with same name (ambiguous map-name)
. map not referenced (dangling map)
. no link-targets in map (empty map)
. link-target missing in area (empty href in area)
. broken link targets in map (broken href in area-tag)
[[missing-alt-attributes]]
=== 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.
[source,html]
== Stats
[small]#last update {docdate}, build with Asciidoctor {asciidoctor-version}#