# metalsmith-broken-link-checker Metalsmith plugin to check for internal broken links ## About 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 `` tags and all `src` attributes of `` tags are checked. This plugin uses [cheerio](https://www.npmjs.com/package/cheerio) to find link and image tags and [urijs](https://www.npmjs.com/package/urijs) to manipulate URLs. I also wrote a [blog post about what I learned developing this plugin](https://davidxmoody.com/publishing-my-first-npm-package/). ## Example In your Metalsmith source dir, you have the following file (`dir1/test-file.html`): ```html (Root-relative link) Error if 'a.html' not in files (Relative link) Error if 'dir1/a.html' not in files (Relative link) Error if 'dir1/a.html' not in files (Relative link) Error if 'a.html' not in files (Root-relative link to dir) Error if 'index.html' not in files (Relative link to dir) Error if 'dir1/dir2/index.html' not in files (Hash fragment link) Always valid (Hash fragment link) Error if 'dir2/index.html' not in files Missing href attribute, always broken (Relative link) Error if 'dir1/testimg.jpg' not in files

(Relative link) Error if 'dir1/testimg.jpg' not in files

(Root-relative link) Error if 'testimg.jpg' not in files

``` 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. ## Installation ``` $ npm install --save metalsmith-broken-link-checker ``` ## CLI Usage In `metalsmith.json`: ```javascript { "source": "src", "destination": "build", "plugins": { "metalsmith-broken-link-checker": true } } ``` ## JavaScript Usage ```javascript var Metalsmith = require('metalsmith') var blc = require('metalsmith-broken-link-checker') Metalsmith(__dirname) // Build your full site here... .use(blc(options)) .build() ``` ### Options #### `allowRegex` (optional) ( default: *null* ) - 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 #### `allowRedirects` (optional) ( default: *false* ) - 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/` or `dir1`) #### `allowAnchors` (optional) ( default: *true* ) - An anchor is an `` tag with a `name` attribute but no `href` attribute (used for jumping to elements on a page with hash fragments) - For example, with `allowAnchors` set to `true`, the following would be allowed: `Anchor text` #### `checkImages` (optional) ( default: *true* ) - Specifies whether or not to check `src` attributes of `` tags #### `checkLinks` (optional) ( default: *true* ) - Specifies whether or not to check `href` attributes of `` tags #### `warn` (optional) ( default: *false* ) - If *false* then throw an `Error` when encountering the first broken link - If *true* then print warnings to stderr for every broken link ## History - 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