{"id":16127283,"url":"https://github.com/justinbeckwith/linkinator","last_synced_at":"2026-02-27T05:16:54.971Z","repository":{"id":38551121,"uuid":"170236232","full_name":"JustinBeckwith/linkinator","owner":"JustinBeckwith","description":"🐿 Scurry around your site and find all those broken links. ","archived":false,"fork":false,"pushed_at":"2025-03-28T22:23:21.000Z","size":3885,"stargazers_count":1062,"open_issues_count":48,"forks_count":84,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-21T09:51:36.756Z","etag":null,"topics":["404","broken-links","link-checker","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JustinBeckwith.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-12T02:13:33.000Z","updated_at":"2025-04-15T09:49:52.000Z","dependencies_parsed_at":"2023-02-08T13:15:31.538Z","dependency_job_id":"8590a5b9-d5c7-47ee-bd77-12e33ca6fc1c","html_url":"https://github.com/JustinBeckwith/linkinator","commit_stats":{"total_commits":313,"total_committers":25,"mean_commits":12.52,"dds":0.5718849840255591,"last_synced_commit":"be229eda83bbd8fbaaa077c6eceb336599ae7359"},"previous_names":[],"tags_count":114,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JustinBeckwith%2Flinkinator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JustinBeckwith%2Flinkinator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JustinBeckwith%2Flinkinator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JustinBeckwith%2Flinkinator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JustinBeckwith","download_url":"https://codeload.github.com/JustinBeckwith/linkinator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250514764,"owners_count":21443208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["404","broken-links","link-checker","typescript"],"created_at":"2024-10-09T21:43:42.467Z","updated_at":"2025-12-28T01:38:47.031Z","avatar_url":"https://github.com/JustinBeckwith.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐿 linkinator - Broken Link Checker\n\n\u003e A super simple site crawler and broken link checker for websites, documentation, and local files.\n\n![linkinator](https://raw.githubusercontent.com/JustinBeckwith/linkinator/main/site/linkinator.webp)\n\n[![npm version](https://img.shields.io/npm/v/linkinator)](https://www.npmjs.com/package/linkinator)\n[![codecov](https://img.shields.io/codecov/c/github/JustinBeckwith/linkinator/main)](https://app.codecov.io/gh/JustinBeckwith/linkinator)\n[![Checked with Biome](https://img.shields.io/badge/Checked_with-Biome-60a5fa?style=flat\u0026logo=biome)](https://biomejs.dev)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079)](https://github.com/semantic-release/semantic-release)\n\n**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.\n\nThis 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:\n\n- 🔥 Easily perform scans on remote sites or local files\n- 🔥 Scan any element that includes links, not just `\u003ca href\u003e`\n- 🔥 Supports redirects, absolute links, relative links, all the things\n- 🔥 Configure specific regex patterns to skip\n- 🔥 Scan markdown files without transpilation\n\n## Installation\n\n### Node.js / npm\n\n```sh\nnpm install linkinator\n```\n\n### Standalone Binaries (no Node.js required)\n\nDon't have Node.js installed? No problem! Browse all releases at [github.com/JustinBeckwith/linkinator/releases](https://github.com/JustinBeckwith/linkinator/releases).\n\nThese binaries are completely standalone - no runtime dependencies needed. Just download, make executable (Linux/macOS), and run!\n\n## Command Usage\n\nYou can use this as a library, or as a CLI.  Let's see the CLI!\n\n```text\n$ linkinator LOCATIONS [ --arguments ]\n\n  Positional arguments\n\n    LOCATIONS\n      Required. Either the URLs or the paths on disk to check for broken links.\n      Supports multiple paths, and globs.\n\n  Flags\n\n    --concurrency\n          The number of connections to make simultaneously. Defaults to 100.\n\n    --config\n        Path to the config file to use. Looks for `linkinator.config.json` by default.\n\n    --directory-listing\n        Include an automatic directory index file when linking to a directory.\n        Defaults to 'false'.\n\n    --clean-urls\n        Enable clean URLs (extensionless links). When enabled, links like '/about'\n        will automatically resolve to '/about.html' if the file exists.\n        Mimics behavior of modern static hosting platforms like Vercel.\n        Defaults to 'false'.\n\n    --format, -f\n        Return the data in CSV or JSON format.\n    \n    --header, -h\n      List of additional headers to be include in the request. use key:value notation.\n        \n    --help\n        Show this command.\n\n    --markdown\n        Automatically parse and scan markdown if scanning from a location on disk.\n\n    --recurse, -r\n        Recursively follow links on the same root domain.\n\n    --check-css\n        Extract and check URLs found in CSS properties (inline styles, \u003cstyle\u003e tags, and external CSS files).\n        This includes url() functions, @import statements, and other CSS URL references.\n        Defaults to false.\n\n    --check-fragments\n        Validate fragment identifiers (URL anchors like #section-name) exist on the target HTML page.\n        Invalid fragments will be marked as broken. Only checks server-rendered HTML (not JavaScript-added fragments).\n        Defaults to false.\n\n    --redirects\n        Control how redirects are handled. Options are 'allow' (default, follows redirects),\n        'warn' (follows but emits warnings), or 'error' (treats redirects as broken).\n\n    --require-https\n        Enforce HTTPS links. Options are 'off' (default, accepts both HTTP and HTTPS),\n        'warn' (accepts both but emits warnings for HTTP), or 'error' (treats HTTP links as broken).\n\n    --allow-insecure-certs\n        Allow invalid or self-signed SSL certificates. Useful for local development with\n        untrusted certificates. Defaults to false.\n\n    --retry,\n        Automatically retry requests that return HTTP 429 responses and include\n        a 'retry-after' header. Defaults to false.\n\n    --retry-errors,\n        Automatically retry requests that return 5xx or unknown response.\n\n    --retry-errors-count,\n        How many times should an error be retried?\n\n    --retry-errors-jitter,\n        Random jitter applied to error retry.\n\n    --server-root\n        When scanning a locally directory, customize the location on disk\n        where the server is started.  Defaults to the path passed in [LOCATION].\n\n    --skip, -s\n        List of urls in regexy form to not include in the check. Can be repeated multiple times.\n\n    --status-code\n        Control how specific HTTP status codes are handled. Format: \"CODE:ACTION\"\n        where CODE is a numeric status code (e.g., 403) or pattern (e.g., 4xx, 5xx)\n        and ACTION is one of: ok (success), warn (success with warning),\n        skip (ignore link), or error (force failure).\n        Can be repeated multiple times. Example: --status-code \"403:warn\" --status-code \"5xx:skip\"\n\n    --timeout\n        Request timeout in ms.  Defaults to 0 (no timeout).\n\n    --url-rewrite-search\n        Pattern to search for in urls.  Must be used with --url-rewrite-replace.\n\n    --url-rewrite-replace\n        Expression used to replace search content.  Must be used with --url-rewrite-search.\n        Example: --url-rewrite-search \"https://example\\.com\" --url-rewrite-replace \"http://localhost:3000\"\n\n    --user-agent\n        The user agent passed in all HTTP requests. Defaults to 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.117 Safari/537.36'\n\n    --verbosity\n        Override the default verbosity for this command. Available options are\n        'debug', 'info', 'warning', 'error', and 'none'.  Defaults to 'warning'.\n```\n\n### Command Examples\n\nYou can run a shallow scan of a website for busted links:\n\n```sh\nnpx linkinator https://jbeckwith.com\n```\n\nThat was fun.  What about local files?  The linkinator will stand up a static web server for yinz:\n\n```sh\nnpx linkinator ./docs\n```\n\nBut that only gets the top level of links.  Lets go deeper and do a full recursive scan!\n\n```sh\nnpx linkinator ./docs --recurse\n```\n\nAw, snap.  I didn't want that to check *those* links.  Let's skip em:\n\n```sh\nnpx linkinator ./docs --skip www.googleapis.com\n```\n\nNeed to skip multiple patterns? Just use `--skip` multiple times:\n\n```sh\nnpx linkinator ./docs --skip www.googleapis.com --skip example.com --skip github.com\n```\n\nThe `--skip` parameter will accept any regex! You can do more complex matching, or even tell it to only scan links with a given domain:\n\n```sh\nnpx linkinator http://jbeckwith.com --skip '^(?!http://jbeckwith.com)'\n```\n\nMaybe you're going to pipe the output to another program.  Use the `--format` option to get JSON or CSV!\n\n```sh\nnpx linkinator ./docs --format CSV\n```\n\nLet's make sure the `README.md` in our repo doesn't have any busted links:\n\n```sh\nnpx linkinator ./README.md --markdown\n```\n\nYou know what, we better check all of the markdown files!\n\n```sh\nnpx linkinator \"**/*.md\" --markdown\n```\n\nNeed to check a static site with clean URLs (extensionless links)?\n\n```sh\nnpx linkinator ./dist --recurse --clean-urls\n```\n\n### 🌰 Strict Link Checking\n\nLike 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:\n\n```sh\nnpx linkinator . --recurse --check-css --check-fragments --redirects error --require-https error\n```\n\n- Scurries through your entire site recursively\n- Sniffs out broken fragment identifiers (like `#section-name`)\n- Gets angry at any redirects (a suspicious acorn is a bad acorn!)\n- Only accepts HTTPS acorns (HTTP is a rotten nut!)\n\n### Configuration file\n\nYou 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.\n\nAll options are optional. It should look like this:\n\n```json\n{\n  \"concurrency\": 100,\n  \"config\": \"string\",\n  \"recurse\": true,\n  \"skip\": \"www.googleapis.com\",\n  \"format\": \"json\",\n  \"silent\": true,\n  \"verbosity\": \"error\",\n  \"timeout\": 0,\n  \"markdown\": true,\n  \"checkCss\": true,\n  \"checkFragments\": true,\n  \"serverRoot\": \"./\",\n  \"directoryListing\": true,\n  \"cleanUrls\": true,\n  \"redirects\": \"allow\",\n  \"requireHttps\": \"off\",\n  \"allowInsecureCerts\": false,\n  \"retry\": true,\n  \"retryErrors\": true,\n  \"retryErrorsCount\": 3,\n  \"retryErrorsJitter\": 5,\n  \"urlRewriteSearch\": \"https://example\\\\.com\",\n  \"urlRewriteReplace\": \"http://localhost:3000\",\n  \"userAgent\": \"Mozilla/4.0 (compatible; MSIE 6.0; MSIE 5.5; Windows NT 5.1)\",\n  \"header\": [\"Authorization:Bearer TOKEN\", \"X-Custom-Header:value\"],\n  \"statusCodes\": {\n    \"403\": \"warn\",\n    \"404\": \"skip\",\n    \"4xx\": \"warn\",\n    \"5xx\": \"skip\"\n  }\n}\n```\n\nFor skipping multiple URL patterns, use an array:\n\n```json\n{\n  \"skip\": [\"www.googleapis.com\", \"example.com\", \"github.com\"]\n}\n```\n\n### Handling Specific Status Codes\n\nSometimes 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.\n\nUse the `--status-code` flag on the command line:\n\n```sh\n# Treat 403 as a warning instead of an error\nnpx linkinator . --status-code \"403:warn\"\n\n# Skip 404 errors entirely\nnpx linkinator . --status-code \"404:skip\"\n\n# Combine multiple status code rules\nnpx linkinator . --status-code \"403:warn\" --status-code \"5xx:skip\"\n```\n\nOr configure it in your `linkinator.config.json`:\n\n```json\n{\n  \"statusCodes\": {\n    \"403\": \"warn\",\n    \"404\": \"skip\",\n    \"4xx\": \"warn\",\n    \"5xx\": \"skip\"\n  }\n}\n```\n\nAvailable actions:\n\n- **`ok`** - Treat as success (link passes)\n- **`warn`** - Treat as success but emit a warning message\n- **`skip`** - Ignore the link entirely (like bot-protected links)\n- **`error`** - Force the link to fail\n\nYou can use specific codes (`\"403\"`) or patterns (`\"4xx\"`, `\"5xx\"`). Specific codes take priority over patterns.\n\nTo load config settings outside the CWD, you can pass the `--config` flag to the `linkinator` CLI:\n\n```sh\nnpx linkinator --config /some/path/your-config.json\n```\n\n## GitHub Actions\n\nYou can use `linkinator` as a GitHub Action as well, using [JustinBeckwith/linkinator-action](https://github.com/JustinBeckwith/linkinator-action):\n\n```yaml\non:\n  push:\n    branches:\n      - main\n  pull_request:\nname: ci\njobs:\n  linkinator:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: JustinBeckwith/linkinator-action@v2\n        with:\n          paths: README.md\n```\n\nTo see all options or to learn more, visit [JustinBeckwith/linkinator-action](https://github.com/JustinBeckwith/linkinator-action).\n\n### Model Context Protocol (MCP)\n\nYou can also use `linkinator` in AI assistants like Claude through the Model Context Protocol using [JustinBeckwith/linkinator-mcp](https://github.com/JustinBeckwith/linkinator-mcp).\n\nThe linkinator-mcp server brings link-checking capabilities directly to AI assistants, enabling automated scanning of webpages and local files through natural language prompts.\n\n**Installation:**\n\n```sh\nnpx install-mcp linkinator-mcp --client claude\n```\n\nThis will automatically configure the MCP server for Claude Desktop, Claude Code, Cursor, and other compatible clients.\n\n**Usage:**\n\nOnce installed, you can check links through natural language:\n\n```text\n\u003e Check all links on https://example.com\n\u003e Scan my documentation recursively and validate anchor fragments\n\u003e Check local files at /path/to/docs\n```\n\nFor more details and manual configuration options, visit [JustinBeckwith/linkinator-mcp](https://github.com/JustinBeckwith/linkinator-mcp).\n\n## API Usage\n\n### linkinator.check(options)\n\nAsynchronous method that runs a site wide scan. Options come in the form of an object that includes:\n\n- `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*.\n- `concurrency` (number) -  The number of connections to make simultaneously. Defaults to 100.\n- `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.\n- `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.\n- `checkCss` (boolean) - Extract and check URLs found in CSS properties (inline styles, `\u003cstyle\u003e` tags, and external CSS files when using `recurse`). This includes `url()` functions, `@import` statements, and other CSS URL references. Defaults to `false`.\n- `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.\n- `serverRoot` (string) - When scanning a locally directory, customize the location on disk\nwhere the server is started.  Defaults to the path passed in `path`.\n- `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.\n- `markdown` (boolean) - Automatically parse and scan markdown if scanning from a location on disk.\n- `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.\n- `directoryListing` (boolean) - Automatically serve a static file listing page when serving a directory.  Defaults to `false`.\n- `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`.\n- `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:\n\n  ```javascript\n  urlRewriteExpressions: [\n    {\n      pattern: /https:\\/\\/example\\.com/,\n      replacement: 'http://localhost:3000'\n    }\n  ]\n  ```\n\n- `userAgent` (string) - The [user agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) that should be passed with each request. This uses a reasonable default.\n- `headers` (object) - Custom HTTP headers to include in all requests. Object with header names as keys and values as strings. These headers are merged with the default headers (including User-Agent). Example: `{ 'Authorization': 'Bearer token', 'X-Custom': 'value' }`.\n\n### linkinator.LinkChecker()\n\nConstructor method that can be used to create a new `LinkChecker` instance.  This is particularly useful if you want to receive events as the crawler crawls.  Exposes the following events:\n\n- `pagestart` (string) - Provides the url that the crawler has just started to scan.\n- `link` (object) - Provides an object with\n  - `url` (string) - The url that was scanned\n  - `state` (string) - The result of the scan.  Potential values include `BROKEN`, `OK`, or `SKIPPED`.\n  - `status` (number) - The HTTP status code of the request.\n\n### Examples\n\n#### Simple example\n\n```js\nimport { LinkChecker } from 'linkinator';\n\nasync function simple() {\n  const checker = new LinkChecker();\n  const results = await checker.check({\n    path: 'http://example.com'\n  });\n\n  // To see if all the links passed, you can check `passed`\n  console.log(`Passed: ${results.passed}`);\n\n  // Show the list of scanned links and their results\n  console.log(results);\n\n  // Example output:\n  // {\n  //   passed: true,\n  //   links: [\n  //     {\n  //       url: 'http://example.com',\n  //       status: 200,\n  //       state: 'OK'\n  //     },\n  //     {\n  //       url: 'http://www.iana.org/domains/example',\n  //       status: 200,\n  //       state: 'OK'\n  //     }\n  //   ]\n  // }\n}\nsimple();\n```\n\n#### Complete example\n\nIn most cases you're going to want to respond to events, as running the check command can kinda take a long time.\n\n```js\nimport { LinkChecker } from 'linkinator';\n\nasync function complex() {\n  // create a new `LinkChecker` that we'll use to run the scan.\n  const checker = new LinkChecker();\n\n  // Respond to the beginning of a new page being scanned\n  checker.on('pagestart', url =\u003e {\n    console.log(`Scanning ${url}`);\n  });\n\n  // After a page is scanned, check out the results!\n  checker.on('link', result =\u003e {\n\n    // check the specific url that was scanned\n    console.log(`  ${result.url}`);\n\n    // How did the scan go?  Potential states are `BROKEN`, `OK`, and `SKIPPED`\n    console.log(`  ${result.state}`);\n\n    // What was the status code of the response?\n    console.log(`  ${result.status}`);\n\n    // What page linked here?\n    console.log(`  ${result.parent}`);\n  });\n\n  // Go ahead and start the scan! As events occur, we will see them above.\n  const result = await checker.check({\n    path: 'http://example.com',\n    // port: 8673,\n    // recurse: true,\n    // Skip multiple URL patterns using an array of regex strings\n    // linksToSkip: [\n    //   'example.com/skip-this',\n    //   'github.com',\n    //   '^https://restricted'\n    // ]\n  });\n\n  // Check to see if the scan passed!\n  console.log(result.passed ? 'PASSED :D' : 'FAILED :(');\n\n  // How many links did we scan?\n  console.log(`Scanned total of ${result.links.length} links!`);\n\n  // The final result will contain the list of checked links, and the pass/fail\n  const brokeLinksCount = result.links.filter(x =\u003e x.state === 'BROKEN');\n  console.log(`Detected ${brokeLinksCount.length} broken links.`);\n}\n\ncomplex();\n```\n\n#### Skipping links example\n\n```js\nimport { LinkChecker } from 'linkinator';\n\nasync function skipExample() {\n  const checker = new LinkChecker();\n\n  // Skip multiple URL patterns using an array\n  const result = await checker.check({\n    path: 'https://example.com',\n    recurse: true,\n    linksToSkip: [\n      'www.google.com',           // Skip all Google links\n      'example.com/skip-me',      // Skip specific paths\n      '^https://internal.corp'    // Skip all internal corp links\n    ]\n  });\n\n  console.log(`Scanned ${result.links.length} links`);\n}\n\nskipExample();\n```\n\n#### Custom headers example\n\nPass custom HTTP headers for authentication or other purposes:\n\n```js\nimport { LinkChecker } from 'linkinator';\n\nasync function customHeadersExample() {\n  const checker = new LinkChecker();\n\n  const result = await checker.check({\n    path: 'https://example.com',\n    headers: {\n      'Authorization': 'Bearer YOUR_TOKEN_HERE',\n      'X-Custom-Header': 'custom-value',\n      'X-API-Key': 'your-api-key'\n    }\n  });\n\n  console.log(`Scan completed: ${result.passed ? 'PASSED' : 'FAILED'}`);\n}\n\ncustomHeadersExample();\n```\n\n**CLI Usage:**\n\n```sh\n# Single header\nnpx linkinator https://example.com --header \"Authorization:Bearer YOUR_TOKEN\"\n\n# Multiple headers\nnpx linkinator https://example.com \\\n  --header \"Authorization:Bearer YOUR_TOKEN\" \\\n  --header \"X-API-Key:your-api-key\"\n\n# Header values can contain colons (e.g., timestamps)\nnpx linkinator https://example.com --header \"X-Timestamp:2024-01-01T00:00:00Z\"\n```\n\n**Common use cases:**\n\n- **Authentication**: Pass JWT tokens or API keys to check authenticated pages\n- **Custom User-Agent**: Override the default user agent (also available via `--user-agent` flag)\n- **API requirements**: Send headers required by API endpoints\n- **Testing**: Simulate different client configurations\n\n**Config file:**\n\n```json\n{\n  \"header\": [\n    \"Authorization:Bearer YOUR_TOKEN\",\n    \"X-Custom-Header:value\"\n  ]\n}\n```\n\n## Tips \u0026 Tricks\n\n### Using a proxy\n\nThis library supports proxies via the `HTTP_PROXY` and `HTTPS_PROXY` environment variables.  This [guide](https://www.golinuxcloud.com/set-up-proxy-http-proxy-environment-variable/) provides a nice overview of how to format and set these variables.\n\n### Globbing\n\nYou may have noticed in the example, when using a glob the pattern is encapsulated in quotes:\n\n```sh\nnpx linkinator \"**/*.md\" --markdown\n```\n\nWithout the quotes, some shells will attempt to expand the glob paths on their own.  Various shells (bash, zsh) have different, somewhat unpredictable behaviors when left to their own devices.  Using the quotes ensures consistent, predictable behavior by letting the library expand the pattern.\n\n### JSON-LD\n\nThis library now scans [JSON-LD](https://json-ld.org/) scripts, verifying URLs that are pre-defined by \u003chttps://schema.org\u003e.\n\n### Debugging\n\nOftentimes when a link fails, it's an easy to spot typo, or a clear 404.  Other times ... you may need more details on exactly what went wrong.  To see a full call stack for the HTTP request failure, use `--verbosity DEBUG`:\n\n```sh\nnpx linkinator https://jbeckwith.com --verbosity DEBUG\n```\n\n### Controlling Output\n\nThe `--verbosity` flag offers preset options for controlling the output, but you may want more control.  Using [`jq`](https://stedolan.github.io/jq/) and `--format JSON` - you can do just that!\n\n```sh\nnpx linkinator https://jbeckwith.com --verbosity DEBUG --format JSON | jq '.links | .[] | select(.state | contains(\"BROKEN\"))'\n```\n\n### Bot Protection (Status 403 and 999)\n\nMany websites use bot protection systems that block automated tools like linkinator. When bot protection is detected, linkinator **skips** these links rather than marking them as broken or valid, since it cannot verify whether the URL is actually valid or broken.\n\n- The link appears with `[403] (bot-protected)` or `[999] (bot-protected)` in the output\n- It does NOT count as a broken link or cause checks to fail\n- It is not counted in the \"scanned links\" total\n- Only visible at INFO verbosity level or higher\n\nThis approach is taken because we cannot distinguish between valid and invalid URLs when blocked.  \n\n#### Cloudflare Bot Protection (Status 403)\n\nCloudflare bot protection returns a `403` status code with the `cf-mitigated` response header when detecting automated tools. Linkinator automatically detects this scenario and skips these links.\n\n#### LinkedIn and Other Sites (Status 999)\n\nLinkedIn and some other sites return a non-standard `999` status code to block automated requests. This status code is used regardless of whether the URL is valid or invalid.\n\n## License\n\n[MIT](LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustinbeckwith%2Flinkinator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustinbeckwith%2Flinkinator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustinbeckwith%2Flinkinator/lists"}