or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdindex.mdlink-scanning.md
tile.json

tessl/npm-linkinator

Find broken links, missing images, etc in your HTML. Scurry around your site and find all those broken links.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/linkinator@6.1.x

To install, run

npx @tessl/cli install tessl/npm-linkinator@6.1.0

index.mddocs/

Linkinator

Linkinator is a comprehensive broken link checker and site crawler that provides both CLI and API functionality for validating links in HTML, markdown, and local files. It features concurrent scanning with configurable parallelism, recursive crawling capabilities, support for various link types (absolute, relative, redirects), regex-based URL filtering for inclusion/exclusion, automatic static server setup for local file scanning, and multiple output formats (JSON, CSV).

Package Information

  • Package Name: linkinator
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install linkinator

Core Imports

import { check, LinkChecker, LinkState, DEFAULT_USER_AGENT } from "linkinator";

For CommonJS:

const { check, LinkChecker, LinkState, DEFAULT_USER_AGENT } = require("linkinator");

Basic Usage

import { check, LinkState } from "linkinator";

// Simple link checking
const result = await check({ path: "https://example.com" });
console.log(`Passed: ${result.passed}`);
console.log(`Total links: ${result.links.length}`);

// Check local files with markdown support
const localResult = await check({
  path: "./docs/",
  recurse: true,
  markdown: true,
});

// Filter broken links
const brokenLinks = localResult.links.filter(
  (link) => link.state === LinkState.BROKEN
);

Architecture

Linkinator is built around several key components:

  • Link Checker: Core scanning engine with event-driven architecture for real-time progress tracking
  • Queue System: Concurrent task management with configurable concurrency and retry mechanisms
  • Static Server: Automatic HTTP server for local file scanning with markdown compilation support
  • Link Parser: HTML parsing engine that extracts links from various HTML attributes and srcset specifications
  • Configuration System: Flexible config file support with CLI flag override capabilities
  • CLI Interface: Command-line tool with comprehensive options for automation and CI/CD integration

Capabilities

Link Scanning

Core link checking functionality for validating URLs and local files. Provides both synchronous batch processing and event-driven real-time scanning.

function check(options: CheckOptions): Promise<CrawlResult>;

class LinkChecker extends EventEmitter {
  check(options: CheckOptions): Promise<CrawlResult>;
  on(event: 'link', listener: (result: LinkResult) => void): this;
  on(event: 'pagestart', listener: (link: string) => void): this;
  on(event: 'retry', listener: (details: RetryInfo) => void): this;
}

Link Scanning

Configuration Management

Configuration system supporting both programmatic options and file-based configuration with CLI flag precedence.

function getConfig(flags: Flags): Promise<Flags>;

interface CheckOptions {
  concurrency?: number;
  port?: number;
  path: string | string[];
  recurse?: boolean;
  timeout?: number;
  markdown?: boolean;
  linksToSkip?: string[] | ((link: string) => Promise<boolean>);
  serverRoot?: string;
  directoryListing?: boolean;
  retry?: boolean;
  retryErrors?: boolean;
  retryErrorsCount?: number;
  retryErrorsJitter?: number;
  urlRewriteExpressions?: UrlRewriteExpression[];
  userAgent?: string;
}

Configuration

Command Line Interface

Command-line tool providing direct access to linkinator functionality with comprehensive options for automation and CI/CD integration.

// CLI executable available at: linkinator
// Usage: linkinator LOCATIONS [--arguments]

The CLI supports all CheckOptions through command-line flags and can output results in multiple formats (TEXT, JSON, CSV) with configurable verbosity levels.

Types

interface CrawlResult {
  passed: boolean;
  links: LinkResult[];
}

interface LinkResult {
  url: string;
  status?: number;
  state: LinkState;
  parent?: string;
  failureDetails?: Array<Error | GaxiosResponse>;
}

interface GaxiosResponse {
  status: number;
  statusText: string;
  headers: Record<string, string>;
  data: any;
  config: any;
}

interface RetryInfo {
  url: string;
  secondsUntilRetry: number;
  status: number;
}

enum LinkState {
  OK = 'OK',
  BROKEN = 'BROKEN',
  SKIPPED = 'SKIPPED',
}

interface UrlRewriteExpression {
  pattern: RegExp;
  replacement: string;
}

/** Default user agent string used for HTTP requests */
const DEFAULT_USER_AGENT: string;