Rocket Logo Rocket Docs Themes Tools Blog
Rocket Logo Rocket


A fast checker for broken links/references in HTML files.

Read the Introducing Check HTML Links - no more bad links Blog post to find out how it came to be and how it works.


  • Checks all html files for broken local links/references (in href, src, srcset)
  • Focuses on the broken reference targets and groups references to it
  • Fast (can process 500-1000 documents in ~2-3 seconds)
  • Has only 3 dependencies (and 19 in the full tree)
  • Uses sax-wasm for parsing streamed HTML


npm i -D check-html-links

CLI flags

root-dirstringthe root directory to serve files from. Defaults to the current working directory
ignore-link-patternstringdo not check links matching the pattern
continue-on-errorbooleanif present it will not exit with an error code - useful while writing or for temporary passing a ci
validate-externalsbooleanif present it will validate external links making a request to the linked url
absolute-base-urlstringthe urls of your website - if provided it will handle absolute links that start with it as internal

Usage Examples

# check a folder _site
npx check-html-links _site

# ignore all links like <a href="/users/123">
npx check-html-links _site --ignore-link-pattern "/users/*" "/users/**/*"

# ignore all links like <a href="/users/123"> & <a href="/users/123/details">
npx check-html-links _site --ignore-link-pattern "/users/*" "/users/**/*"

# check external urls
npx check-html-links _site --validate-externals

# check external urls but treat links like as internal
npx check-html-links _site --validate-externals --absolute-base-url

Example Output

Test Run Screenshot


Checking the output of 11ty-website with 13 missing reference targets (used by 516 links) while checking 501 files. (on January 17, 2021)

ToolLines printedTimesLangDependency Tree
hyperlink684m 20snode481