linkinator

linkinator - Broken Link Checker

A super simple site crawler and broken link checker for websites, documentation, and local files.

Linkinator is a powerful broken link checker that crawls websites and validates all links automatically. Whether you're checking a live website, local HTML files, or markdown documentation, this link checker tool will find broken links, dead links, and invalid URLs quickly and efficiently.

This link validator is perfect for SEO audits, quality assurance, continuous integration, and maintaining healthy websites. The linkinator broken link checker provides both an API and CLI for crawling websites and validating links. It's got a ton of sweet features:

• Easily perform scans on remote sites or local files
• Scan any element that includes links, not just ``
• Supports redirects, absolute links, relative links, all the things
• Configure specific regex patterns to skip
• Scan markdown files without transpilation

Installation

Node.js / npm

npm install linkinator

Standalone Binaries (no Node.js required)

Don't have Node.js installed? No problem! Browse all releases at github.com/JustinBeckwith/linkinator/releases.

These binaries are completely standalone - no runtime dependencies needed. Just download, make executable (Linux/macOS), and run!

Docker Usage

Run linkinator using Docker with the same commands as the CLI. The image is available on GitHub Container Registry at ghcr.io/justinbeckwith/linkinator.

Basic Usage:

docker run ghcr.io/justinbeckwith/linkinator LOCATION [ --arguments ]

For reproducible builds, pin to a specific version:

docker run ghcr.io/justinbeckwith/linkinator:3.4.0 LOCATION [ --arguments ]

Examples: Check a live website:

docker run ghcr.io/justinbeckwith/linkinator https://jbeckwith.com

Check local files in your current directory (mount your directory as a volume):

docker run -v "$(pwd)":/usr/src/app -w /usr/src/app ghcr.io/justinbeckwith/linkinator . --recurse

This command mounts your current directory ($(pwd)) to /usr/src/app inside the container and sets it as the working directory. Then, linkinator scans the . directory within the container, recursively.

Command Usage

You can use this as a library, or as a CLI. Let's see the CLI!

…

Command Examples

You can run a shallow scan of a website for busted links:

npx linkinator https://jbeckwith.com

That was fun. What about local files? The linkinator will stand up a static web server for yinz:

npx linkinator ./docs

But that only gets the top level of links. Lets go deeper and do a full recursive scan!

npx linkinator ./docs --recurse

Aw, snap. I didn't want that to check those links. Let's skip em:

npx linkinator ./docs --skip www.googleapis.com

Need to skip multiple patterns? Just use --skip multiple times:

npx linkinator ./docs --skip www.googleapis.com --skip example.com --skip github.com

The --skip parameter will accept any regex! You can do more complex matching, or even tell it to only scan links with a given domain:

npx linkinator http://jbeckwith.com --skip '^(?!http://jbeckwith.com)'

Maybe you're going to pipe the output to another program. Use the --format option to get JSON or CSV!

npx linkinator ./docs --format CSV

Let's make sure the README.md in our repo doesn't have any busted links:

npx linkinator ./README.md --markdown

You know what, we better check all of the markdown files!

npx linkinator "**/*.md" --markdown

Need to check a static site with clean URLs (extensionless links)?

npx linkinator ./dist --recurse --clean-urls

To scan every page declared by a site's sitemap without recursively discovering pages through links, use --sitemap:

npx linkinator https://example.com --sitemap

Sitemap indexes are followed recursively, including index entries that use query strings for pagination. For a custom location, use --sitemap-url; repeat the option to load multiple sitemaps. --sitemap-url cannot be combined with --sitemap:

npx linkinator https://example.com --sitemap-url https://example.com/custom-sitemap.xml

Sitemap mode scans the pages listed in the map and validates their links. If --recurse is also supplied, same-site pages linked from those seeds are crawled recursively as well.

Strict Link Checking

Like a diligent squirrel inspecting every acorn before storing it for winter, you can configure linkinator to be extremely picky about your links. Here's how to go full squirrel:

npx linkinator . --recurse --check-css --check-fragments --redirects error --require-https error

• Scurries through your entire site recursively
• Sniffs out broken fragment identifiers (like #section-name)
• Gets angry at any redirects (a suspicious acorn is a bad acorn!)
• Only accepts HTTPS acorns (HTTP is a rotten nut!)

Configuration file

You can pass options directly to the linkinator CLI, or you can define a config file. By default, linkinator will look for a linkinator.config.json file in the current working directory.

All options are optional. It should look like this:

…

For skipping multiple URL patterns, use an array:

{
  "skip": ["www.googleapis.com", "example.com", "github.com"]
}

Handling Specific Status Codes

Sometimes you need fine-grained control over how linkinator handles specific HTTP status codes. For example, some sites aggressively block crawlers with 403 responses, or you might want to treat certain errors as warnings rather than failures.

Use the --status-code flag on the command line:

# Treat 403 as a warning instead of an error
npx linkinator . --status-code "403:warn"

# Skip 404 errors entirely
npx linkinator . --status-code "404:skip"

# Combine multiple status code rules
npx linkinator . --status-code "403:warn" --status-code "5xx:skip"

Or configure it in your linkinator.config.json:

{
  "statusCodes": {
    "403": "warn",
    "404": "skip",
    "4xx": "warn",
    "5xx": "skip"
  }
}

Available actions:

• ok - Treat as success (link passes)
• warn - Treat as success but emit a warning message
• skip - Ignore the link entirely (like bot-protected links)
• error - Force the link to fail

You can use specific codes ("403") or patterns ("4xx", "5xx"). Specific codes take priority over patterns.

To load config settings outside the CWD, you can pass the --config flag to the linkinator CLI:

npx linkinator --config /some/path/your-config.json

GitHub Actions

You can use linkinator as a GitHub Action as well, using JustinBeckwith/linkinator-action:

on:
  push:
    branches:
      - main
  pull_request:
name: ci
jobs:
  linkinator:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: JustinBeckwith/linkinator-action@v2
        with:
          paths: README.md

To see all options or to learn more, visit JustinBeckwith/linkinator-action.

Model Context Protocol (MCP)

You can also use linkinator in AI assistants like Claude through the Model Context Protocol using JustinBeckwith/linkinator-mcp.

The linkinator-mcp server brings link-checking capabilities directly to AI assistants, enabling automated scanning of webpages and local files through natural language prompts.

Installation:

npx install-mcp linkinator-mcp --client claude

This will automatically configure the MCP server for Claude Desktop, Claude Code, Cursor, and other compatible clients.

Usage:

Once installed, you can check links through natural language:

> Check all links on https://example.com
> Scan my documentation recursively and validate anchor fragments
> Check local files at /path/to/docs

For more details and manual configuration options, visit JustinBeckwith/linkinator-mcp.

API Usage

linkinator.check(options)

Asynchronous method that runs a site wide scan. Options come in the form of an object that includes:

• path (string|string[]) - A fully qualified path to the url to be scanned, or the path(s) to the directory on disk that contains files to be scanned. required.

• concurrency (number) - The number of connections to make simultaneously. Defaults to 100.

• port (number) - When the path is provided as a local path on disk, the port on which to start the temporary web server. Defaults to a random high range order port.

• recurse (boolean) - By default, all scans are shallow. Only the top level links on the requested page will be scanned. By setting recurse to true, the crawler will follow all links on the page, and continue scanning links on the same domain for as long as it can go. Results are cached, so no worries about loops.

• sitemap (boolean|string|string[]) - Use sitemap page URLs as initial crawl targets. Set to true to load /sitemap.xml from each HTTP path, or provide one or more explicit sitemap URLs. Sitemap indexes are followed recursively; combine with recurse to discover additional same-domain pages from those targets.

• checkCss (boolean) - Extract and check URLs found in CSS properties (inline styles, `` tags, and external CSS files when using recurse). This includes url() functions, @import statements, and other CSS URL references. Defaults to false.

• checkFragments (boolean) - Validate fragment identifiers against server-rendered HTML. Defaults to false.

• fragmentsToSkip (array | function) - Regular expression strings matched against decoded fragment identifiers, or an async function receiving the fragment and full URL. Matching fragments are reported as skipped while the underlying URL is still checked.

• retry (boolean|RetryConfig) - Automatically retry requests that respond with an HTTP 429, and include a retry-after header. The RetryConfig option is a placeholder for fine-grained controls to be implemented at a later time, and is only included here to signal forward-compatibility.

• serverRoot (string) - When scanning a locally directory, customize the location on disk where the server is started. Defaults to the path passed in path.

• timeout (number) - By default, requests made by linkinator do not time out (or follow the settings of the OS). This option (in milliseconds) will fail requests after the configured amount of time.

• markdown (boolean) - Automatically parse and scan markdown if scanning from a location on disk.

• linksToSkip (array | function) - An array of regular expression strings that should be skipped (e.g., ['example.com', 'github.com', '^http://']), OR an async function that's called for each link with the link URL as its only argument. Return a Promise that resolves to true to skip the link or false to check it.

• directoryListing (boolean) - Automatically serve a static file listing page when serving a directory. Defaults to false.

• cleanUrls (boolean) - Enable clean URLs (extensionless links). When enabled, links like /about will automatically resolve to /about.html if the file exists. Mimics behavior of modern static hosting platforms like Vercel. Defaults to false.

• urlRewriteExpressions (array) - Collection of objects that contain a search pattern, and replacement. Use this to rewrite URLs before they are checked. For example, to rewrite a production URL to a local development URL:

  urlRewriteExpressions: [
    {
      pattern: /https:\/\/example\.com/,
      replacement: 'http://localhost:3000'
    }
  ]
  

  JavaScri