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.htmlinside it, a link without a trailing slash also matches anindex.htmlinside 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>