Metalsmith plugin to check for internal broken links
Small typos can often result in unexpected broken links. This plugin aims to catch them as early as possible.
It checks for relative and root-relative links which do not have a corresponding file in the Metalsmith pipeline. It (currently) ignores all absolute links.
Any broken links will cause an Error to be thrown (or a warning to be printed if options.warn is set).
By default, all href attributes of <a> tags and all src attributes of <img> tags are checked.
This plugin uses cheerio to find link and image tags and urijs to manipulate URLs.
I also wrote a blog post about what I learned developing this plugin.
In your Metalsmith source dir, you have the following file (dir1/test-file.html):
<!DOCTYPE html>
<html>
<body>
<a href="/a.html">(Root-relative link) Error if 'a.html' not in files</a>
<a href="a.html">(Relative link) Error if 'dir1/a.html' not in files</a>
<a href="./a.html">(Relative link) Error if 'dir1/a.html' not in files</a>
<a href="../a.html">(Relative link) Error if 'a.html' not in files</a>
<a href="/">(Root-relative link to dir) Error if 'index.html' not in files</a>
<a href="dir2/">(Relative link to dir) Error if 'dir1/dir2/index.html' not in files</a>
<a href="#fragment">(Hash fragment link) Always valid</a>
<a href="/dir2/#fragment">(Hash fragment link) Error if 'dir2/index.html' not in files</a>
<a>Missing href attribute, always broken</a>
<img src="testimg.jpg" alt="(Relative link) Error if 'dir1/testimg.jpg' not in files">
<img src="/testimg.jpg" alt="(Root-relative link) Error if 'testimg.jpg' not in files">
</body>
</html>Note that links to directories are allowed if they have a trailing slash (the index.html file will be looked for). However links to directories without a trailing slash are not allowed unless the allowRedirects option is set.
$ npm install --save metalsmith-broken-link-checker
In metalsmith.json:
{
"source": "src",
"destination": "build",
"plugins": {
"metalsmith-broken-link-checker": true
}
}var Metalsmith = require('metalsmith')
var blc = require('metalsmith-broken-link-checker')
Metalsmith(__dirname)
// Build your full site here...
.use(blc(options))
.build()- Optional regex gets matched against every found URL
- Use it if you want to allow some specific URLs which would otherwise get recognised as broken
- If false then links to directories will only be allowed if the link ends with a trailing slash (e.g.
dir1/) - If true then links to directories will be allowed with or without a trailing slash (e.g.
dir1/ordir1)
- An anchor is an
<a>tag with anameattribute but nohrefattribute (used for jumping to elements on a page with hash fragments) - For example, with
allowAnchorsset totrue, the following would be allowed:<a name="anchor">Anchor text</a>
- Specifies whether or not to check
srcattributes of<img>tags
- Specifies whether or not to check
hrefattributes of<a>tags
- If false then throw an
Errorwhen encountering the first broken link - If true then print warnings to stderr for every broken link
- 0.1.9 Add CI badges to README
- 0.1.8 Add allowRedirects option
- 0.1.7 Change URIjs to urijs
- 0.1.6 Fix forward slash Windows path bug
- 0.1.5 Add allowAnchors option
- 0.1.4 Normalize file paths for Windows
- 0.1.3 Fail in the correct way for missing href attribute
- 0.1.2 Updated README
- 0.1.1 Updated README
- 0.1.0 First release