/ 
HTML-Anchor-Audit-0.001
/ README.md

HTML::Anchor::Audit

An offline Perl library and command for checking section links in UTF-8 HTML articles. It reports missing #targets, repeated IDs and ambiguous references with line numbers, Unicode character columns and UTF-8 byte positions.

This is useful before publishing saved article HTML, including Gutenberg exports, or inside an editor/static-content pipeline. The library accepts strings; the command reads local files. Neither fetches URLs, changes articles nor sends telemetry.

Install

Requires Perl 5.16 or later and HTML::Parser 3.72 or later. Other runtime dependencies ship with Perl. From a source release:

cpanm HTML::Parser
perl Makefile.PL
make
make test
make install

On Strawberry Perl for Windows, use gmake instead of make. To try the source before installation:

perl -Ilib script/html-anchor-audit examples/article.html
perl -Ilib script/html-anchor-audit --json examples/article.html

The example intentionally contains a missing target and a repeated ID, so it exits with status 1. Use --help for limits. Exit status 2 means an input or usage error.

Library API

use utf8;
use HTML::Anchor::Audit qw(audit_html);

my $report = audit_html('<a href="#intro">Start</a><h2 id="intro">Intro</h2>');
for my $issue (@{ $report->{issues} }) {
    printf "%s at %d:%d\n", $issue->{code}, $issue->{line}, $issue->{column};
}

Use audit_utf8 for UTF-8 bytes or audit_html for already decoded characters. API documentation is in lib/HTML/Anchor/Audit.pm. Unicode normalization is only a diagnostic hint; it never silently changes IDs or makes an invalid target valid.

Scope and alternatives

Only fragment-only links on <a> and <area> are checked against static IDs and legacy <a name>. Exact and percent-decoded matches, Arabic IDs, HTML attribute entities and source positions are supported. A nonempty first <base href> and text-fragment directives cause links to be marked ignored. Template contents are ignored. See POD for the complete matching and report contract.

This is not a complete HTML5 DOM parser, WordPress validator or external link checker. Malformed nesting, duplicate attributes, SVG/XML, scripting-dependent noscript content and some HTML5 entity edge cases can differ from a browser. Theme-generated and JavaScript-generated IDs are unavailable in saved content.

The W3C Link Checker already checks anchors and fragments and is better suited to a website crawl. HTML::SimpleLinkExtor extracts links; HTML::Lint checks broader HTML errors; WWW::LinkRot checks remote URLs. This module has a narrower offline API, structured source locations and Unicode normalization hints. See docs/comparison.md for the pre-release comparison.

Development

prove -lr t
perl Makefile.PL
make disttest

The test suite exercises valid/broken HTML, Unicode, encoded IDs, matching precedence, ignored contexts, UTF-8 locations, limits, CLI output, exit codes and preservation of input files. See docs/validation.md for the actual environments tested.

Maintainer

Nedal Shabaan, Idraaak. MIT license. Report reproducible bugs through GitHub issues.