HiD-BrokenLink

A broken link checker for the HiD static site framework.

After publishing, it scans the generated HTML, CSS and (optionally) JavaScript files and verifies that every local reference — links, images, stylesheets, scripts, inline url()s — points to a file that actually exists in the destination.

Requirements

• Perl 5.14+
• HiD
• Moose, Path::Tiny, HTML::Parser

Installation

cpanm byterazor::HiD::BrokenLink

Usage

Add +byterazor::HiD::BrokenLink to the plugins key in your HiD config. The + prefix tells HiD to use the full class name rather than looking in the HiD::Generator:: namespace:

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

The check runs after publishing and is enabled by default.

Configuration

| Key | Default | Description | | --- | --- | --- | | brokenlink.enabled | 1 | Run the check. | | brokenlink.check_html | 1 | Check href/src/data/poster attributes and inline <style> blocks in HTML files. | | brokenlink.check_css | 1 | Check url() references and @import statements in CSS files. | | brokenlink.check_js | 0 | Check quoted root-relative asset references in JavaScript files. | | brokenlink.strip_baseurl | 1 | Treat absolute URLs matching the site baseurl as local. | | brokenlink.exclude | — | Arrayref of regexes; matching references are not checked. | | brokenlink.report | — | Path of a text report listing the broken references, relative to the working directory (not the site destination). | | brokenlink.fail_on_broken | 0 | Fail the build when broken references are found. |

Link resolution

• External URLs (other schemes, other hosts), protocol-relative URLs and pure fragments are skipped.
• Query strings and fragments are stripped from the remaining links before they are checked.
• A link is 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.
• A <base href> element is respected when resolving relative references. A file with an external base URL is not checked at all.
• References that resolve outside the destination are reported as broken.

Examples

Basic

The plugin is enabled by default, no extra config is needed:

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

Fail the build on broken links

brokenlink:
  fail_on_broken: 1

Check JavaScript and write a report

brokenlink:
  check_js: 1
  report: _reports/brokenlinks.txt
  exclude:
    - '\.min\.js$'

License

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

Author

Dominik Meyer <dmeyer@federationhq.de>