/ 
byterazor-HiD-BrokenLink-0.1.0
/ byterazor::HiD::BrokenLink

NAME

byterazor::HiD::BrokenLink - broken link checker for published sites

VERSION

version 0.1.0

DESCRIPTION

This plugin checks, after the site has been published, that every local file reference in the published output points to an existing file.

It scans

  • HTML files - the href, src, data and poster attributes of any element, plus url() references in inline <style> blocks.

  • CSS files - url() references and @import statements.

  • JavaScript files (opt-in) - quoted root-relative references to known asset types.

External URLs (other schemes and other hosts), pure fragments and protocol-relative URLs are skipped. Query strings and fragments are stripped from the remaining links before they are checked. If the site has a baseurl, absolute URLs matching it are treated as local. A <base href> element is respected when resolving relative references; a file with an external base URL is not checked at all.

Enable it by adding +byterazor::HiD::BrokenLink to the plugins key in your config:

plugins:
  - '+byterazor::HiD::BrokenLink'

You may set the following brokenlink.* config keys:

brokenlink.enabled

Run the check. Defaults to 1.

brokenlink.check_html

Check HTML files. Defaults to 1.

brokenlink.check_css

Check CSS files. Defaults to 1.

brokenlink.check_js

Check JavaScript files. Defaults to 0.

brokenlink.strip_baseurl

Treat absolute URLs matching the site baseurl as local. Defaults to 1.

brokenlink.exclude

Arrayref of regexes; references matching any of them are not checked.

brokenlink.report

Path of a text report listing the broken references. The path is interpreted relative to the current working directory, not relative to the site destination. Only written when set.

brokenlink.fail_on_broken

Die, failing the build, when broken references are found. Defaults to 0.

A link is considered OK if it matches an existing file or directory. A link with a trailing slash matches an existing directory or an index.html inside it; a link without a trailing slash also matches an index.html inside a directory of the same name.

METHODS

after_publish

Checks the published site for broken local references, reports each of them via $site-WARN>, emits a summary via $site-INFO>, optionally writes a report file, and dies when brokenlink.fail_on_broken is set and broken references were found.

scan

Walks the site destination, extracts every reference from the scannable files and checks the local ones for existence. Returns a result hashref with the keys files, dirs, files_checked, checked and broken (an arrayref of { src , link , resolved , reason? }).

_extract_html

Extracts references from an HTML document using HTML::Parser. Returns an arrayref of reference values and the value of the first <base href> element (or undef). Contents of <style> elements are collected and scanned for CSS url() references.

_extract_css_urls

Extracts the reference values of url() and @import statements from CSS text.

_extract_js_refs

Best-effort extraction of root-relative asset references from JavaScript: quoted strings starting at the site root that end with a known asset extension.

_base_directories

Given a <base href> value (or undef), the directory the source file lives in, and the site baseurl prefix, returns the directory relative links must be resolved against and a flag that is true when the base URL is external (in which case nothing can be resolved locally).

_classify

Classifies a reference. Returns undef for external references and for references that are empty once fragment and query string are stripped. Returns { escape => 1 } when a relative reference resolves outside the destination, and otherwise { rel => $path , trailing => $bool }.

_write_report

Writes a plain-text report of the broken references to the given path, which is interpreted relative to the current working directory (or taken as absolute), not relative to the site destination.

AUTHOR

Dominik Meyer <dmeyer@federationhq.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Dominik Meyer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.