@umbrelladocs/linkspector

v0.5.3

Published

24 days ago

Uncover broken links in your content.

Linkspector is a CLI tool that checks for dead hyperlinks in your files. It supports Markdown and AsciiDoc, with a rich interactive TUI for local use and clean output for CI/CD pipelines.

Why Linkspector?

Fewer false positives - Uses Puppeteer headless Chrome as a fallback, so JavaScript-rendered pages and bot-protected links are checked correctly.
Rich terminal UI - Animated progress bar, live error stream, and grouped results when running interactively. Falls back to plain output in CI automatically.
Built for CI/CD - First-class GitHub Action with RDJSON output for reviewdog integration.
Standalone binaries - Download a single executable from Releases. No Node.js required.

Trusted by

If you are using this on production, consider buying me a coffee ☕.

Installation

npm (recommended)

Prerequisites: Node.js 18.18.0+ and a supported Chromium/Chrome installation are required. On Linux you may also need system libraries. See PREREQUISITES.md for full details.

npm install -g @umbrelladocs/linkspector

Standalone binary

Download a prebuilt binary from GitHub Releases. No Node.js or npm required.

| Platform | Architecture | File | | -------- | ------------ | ----------------------------- | | Linux | x64 | linkspector-linux-x64 | | Linux | ARM64 | linkspector-linux-arm64 | | macOS | x64 (Intel) | linkspector-macos-x64 | | macOS | ARM64 (M1+) | linkspector-macos-arm64 | | Windows | x64 | linkspector-windows-x64.exe |

# Linux/macOS
chmod +x linkspector-linux-x64
sudo mv linkspector-linux-x64 /usr/local/bin/linkspector

Note: The standalone binary requires Google Chrome or Chromium installed on your system for the Puppeteer fallback pass. Linkspector auto-detects Chrome in common paths. For non-standard locations, set PUPPETEER_EXECUTABLE_PATH:
export PUPPETEER_EXECUTABLE_PATH=/path/to/chrome
linkspector check

GitHub Action

See action-linkspector for CI/CD integration.

Usage

linkspector check [options]

Options

| Flag | Description | | --------------------- | ------------------------------------------------------------ | | -c, --config <path> | Custom configuration file path (default: .linkspector.yml) | | -j, --json | Output results in RDJSON format | | -s, --showstat | Display link check statistics | | -q, --quiet | No output, exit code only |

Examples

# Check with default config
linkspector check

# Custom config file
linkspector check -c /path/to/config.yml

# JSON output for CI (RDJSON format)
linkspector check -j

# Show statistics table
linkspector check -s

# Quiet mode (exit code only, useful in scripts)
linkspector check -q

Output modes

Interactive terminal (TUI) - When running in a terminal, Linkspector shows an animated progress bar, live error stream grouped by file, and a summary bar:

  > Linkspector v0.4.8
  ──────────────────────────────────────────────
  * Checking: docs/api/auth.md
  Files   ████████████░░░░░░░░  12/47  25%
  Links   89 checked . 2 failed
  ──────────────────────────────────────────────

  docs/setup.md
    L12:5  x https://example.com/old-page     404 Not Found
    L34:3  x https://api.example.com/removed   ECONNREFUSED

CI / piped output - Automatically detected via stdout.isTTY and the CI environment variable. Uses plain text output compatible with existing CI pipelines:

docs/setup.md:12:5: https://example.com/old-page Status:404 Not Found
Error: Some hyperlinks in the specified files are invalid.

JSON (-j) - Outputs RDJSON for reviewdog integration. Validated by @umbrelladocs/rdformat-validator.

Configuration

Linkspector uses .linkspector.yml in the current directory. If not found, it uses the default configuration:

dirs:
  - .
useGitIgnore: true

Configuration options

| Option | Description | Required | | ------------------------------------------------- | ------------------------------------------------------ | -------------------------- | | files | Files to check for broken links | Yes, if dirs is not set | | dirs | Directories to search for files | Yes, if files is not set | | excludedFiles | Files to skip | No | | excludedDirs | Directories to skip | No | | fileExtensions | File extensions to check (default: ['md']) | No | | baseUrl | Base URL for relative links | No | | ignorePatterns | Regex patterns for URLs to skip | No | | replacementPatterns | Regex find/replace for URLs before checking | No | | aliveStatusCodes | Additional HTTP status codes considered valid | No | | useGitIgnore | Respect .gitignore rules (default: true) | No | | modifiedFilesOnly | Only check git-modified files | No | | httpHeaders | Custom HTTP headers per domain | No | | followRedirects | Follow HTTP redirects (default: true) | No | | timeout | Request timeout in ms (default: 30000) | No | | retryCount | Retry attempts with exponential backoff (default: 3) | No | | userAgent | Custom User-Agent string | No | | ignoreSslErrors | Skip SSL certificate validation | No |

Files to check

files:
  - README.md
  - docs/guide.md

Directories to search

dirs:
  - ./
  - docs/

Excluded files

excludedFiles:
  - ./CHANGELOG.md
  - vendor/README.md

Excluded directories

excludedDirs:
  - ./node_modules
  - vendor/

File extensions

fileExtensions:
  - md
  - adoc

Base URL

baseUrl: https://example.com

Ignore patterns

ignorePatterns:
  - pattern: '^https://example\\.com/skip/.*$'
  - pattern: "^(ftp)://[^\\s/$?#]*\\.[^\\s]*$"

Replacement patterns

replacementPatterns:
  - pattern: "(https?://example\\.com)/(\\w+)/(\\d+)"
    replacement: '$1/id/$3'

Alive status codes

aliveStatusCodes:
  - 200
  - 201
  - 204

Use .gitignore

useGitIgnore: true

Check modified files only

modifiedFilesOnly: true

Requires git on your system PATH. Only checks files changed in the last commit.

HTTP headers

Use environment variables for secrets:

httpHeaders:
  - url:
      - https://example1.com
    headers:
      Foo: Bar
  - url:
      - https://example2.com
    headers:
      Authorization: ${AUTH_TOKEN}

Follow redirects

followRedirects: false # Report redirects as errors instead of following them

true (default): Follows redirects; reports the final destination status.
false: Reports any redirect (301, 302, etc.) as an error.

Timeout

timeout: 60000 # 60 seconds

Range: 1000-120000 ms. Applies to both fetch and Puppeteer passes.

Retry count

retryCount: 5

Range: 0-10. Uses exponential backoff (1s, 2s, 4s...) and respects Retry-After headers.

User agent

userAgent: 'MyLinkChecker/1.0'

Ignore SSL errors

ignoreSslErrors: true

Warning: Only enable this for trusted servers (e.g., internal servers with self-signed certificates).

Full example

files:
  - README.md
dirs:
  - ./docs
excludedFiles:
  - ./CHANGELOG.md
excludedDirs:
  - ./vendor
baseUrl: https://example.com
ignorePatterns:
  - pattern: '^https://example\\.com/skip/.*$'
replacementPatterns:
  - pattern: "(https?://example\\.com)/(\\w+)/(\\d+)"
    replacement: '$1/id/$3'
httpHeaders:
  - url:
      - https://api.example.com
    headers:
      Authorization: ${AUTH_TOKEN}
aliveStatusCodes:
  - 200
  - 204
useGitIgnore: true
followRedirects: true
timeout: 60000
retryCount: 5
userAgent: 'MyLinkChecker/1.0'
ignoreSslErrors: false

AsciiDoc Support

Linkspector checks AsciiDoc files through the same CLI, including direct URLs and link: macros. Set fileExtensions to include AsciiDoc:

fileExtensions:
  - md
  - adoc

The AsciiDoc parser handles:

Anchors ([[...]], [[[...]]], [#...], anchor:...[])
Internal references (<<...>>, xref:...[])
External document references (file.adoc#anchor)
Link macros (link:url[text])
Comment-aware parsing (ignores // and ////...//// blocks)

Docker

# Build the image
git clone [email protected]:UmbrellaDocs/linkspector.git
cd linkspector
docker build --no-cache --pull --build-arg LINKSPECTOR_PACKAGE= -t umbrelladocs/linkspector .

# Check links (mount your project at /app)
docker run --rm -it -v $PWD:/app umbrelladocs/linkspector \
  bash -c 'linkspector check'

# With custom config
docker run --rm -it -v $PWD:/app umbrelladocs/linkspector \
  bash -c 'linkspector check -c /app/custom-config.yml'

Building from Source

Prerequisites

npm build: Node.js >= 20
Bun build: Bun runtime

Install dependencies

npm install

Run tests

npm test

Build standalone binaries

Two build systems are available:

| Command | Runtime | TUI Support | Notes | | -------------------------- | ----------- | ----------------- | ------------------------------------------ | | npm run build:binary | Node.js SEA | Plain output only | Uses esbuild + postject | | npm run build:binary:bun | Bun | Full TUI | Smaller binary, supports cross-compilation |

# Node.js SEA binary (plain renderer, no TUI)
npm run build:binary

# Bun binary (full TUI with ink)
npm run build:binary:bun

# Bun cross-compilation
bun scripts/build-bun.mjs --target bun-linux-x64
bun scripts/build-bun.mjs --target bun-linux-arm64
bun scripts/build-bun.mjs --target bun-darwin-arm64
bun scripts/build-bun.mjs --target bun-windows-x64

Build with Docker

# Linux binary for current architecture
docker build -f Dockerfile.buildbinary -o dist/ .

# Cross-architecture builds
docker buildx build --platform linux/arm64 -f Dockerfile.buildbinary -o dist/ .

AI Agent / LLM Usage

AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) can use Linkspector directly via npx:

npx @umbrelladocs/linkspector check -j

The -j flag outputs structured RDJSON, ideal for machine consumption. Use -q for a simple pass/fail exit code.

This repository includes an llms.txt file with full usage and configuration details for AI agent discovery.

For deeper integration, use the Linkspector MCP Server to expose Linkspector as a native tool in Claude Desktop, Claude Code, VS Code, Cursor, and other MCP-compatible clients.

Contributing

See CONTRIBUTING.md for guidelines.