Skip to main content
This guide will help you check your first links with Linkspector. You’ll learn how to run a basic check, create a configuration file, and understand the output.

​
Prerequisites

Make sure you have Linkspector installed. If not, see the installation guide. 
linkspector --version

​
Quick Check with Default Configuration

The fastest way to get started is to run Linkspector with its default configuration.
1

Navigate to your project

Open your terminal and navigate to the directory containing your documentation files:
cd /path/to/your/docs
2

Run the check command

Execute the check command:
linkspector check
Linkspector will display a message: “Configuration file not found. Using default configuration.” and check all files in the current directory.
3

Review the results

If all links are valid, you’ll see:
✨ Success: All hyperlinks in the specified files are valid.
If there are broken links, you’ll see detailed error messages:
README.md:42:15: 🚫 https://example.com/broken-link Status:404 Cannot reach link
💥 Error: Some hyperlinks in the specified files are invalid.

​
Create a Configuration File

For more control over which files to check and how to check them, create a .linkspector.yml configuration file.
1

Create the configuration file

Create a file named .linkspector.yml in your project root:
touch .linkspector.yml
2

Add basic configuration

Add the following content to configure Linkspector for your project:
.linkspector.yml
# Directories to search for files
dirs:
  - ./docs
  - ./README.md

# Respect .gitignore rules
useGitIgnore: true

# Exclude specific directories
excludedDirs:
  - ./node_modules
  - ./build

# Exclude specific files
excludedFiles:
  - ./docs/draft.md

# Status codes that indicate a link is alive
aliveStatusCodes:
  - 200
  - 201
  - 204
  - 301
  - 302
At minimum, you must specify either dirs or files in your configuration.
3

Run with your configuration

Run the check command again. Linkspector will automatically detect and use your .linkspector.yml file:
linkspector check

​
View Statistics

Get detailed statistics about your link checking with the --showstat flag: 
linkspector check --showstat
This displays a comprehensive summary: 
💀📊 Linkspector check stats
┌───────────────────────────────┬────────┐
│ 🟰 Total files checked        │     12 │
├───────────────────────────────┼────────┤
│ 🔗 Total links checked        │    156 │
├───────────────────────────────┼────────┤
│ 🌐 Hyperlinks                 │     89 │
├───────────────────────────────┼────────┤
│ 📁 File and header links      │     64 │
├───────────────────────────────┼────────┤
│ ✉️  Email links (Skipped)      │      3 │
├───────────────────────────────┼────────┤
│ ✅ Working links              │    154 │
├───────────────────────────────┼────────┤
│ 🚫 Failed links               │      2 │
└───────────────────────────────┴────────┘

​
Advanced Configuration Example

Here’s a more advanced configuration that demonstrates additional features:
.linkspector.yml
# Check specific files and directories
files:
  - README.md
  - CONTRIBUTING.md
dirs:
  - ./docs

# Exclude patterns
excludedDirs:
  - ./node_modules
  - ./.git
excludedFiles:
  - ./docs/archive/old-doc.md

# Base URL for relative links
baseUrl: https://linkspector.dev

# Ignore specific URL patterns (regex)
ignorePatterns:
  - pattern: '^https://twitter\.com/.*$'
  - pattern: '^https://linkedin\.com/.*$'
  - pattern: '^ftp://.*$'

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

# Custom HTTP headers for authenticated endpoints
httpHeaders:
  - url:
      - https://api.example.com
    headers:
      Authorization: ${API_TOKEN}
      User-Agent: Linkspector

# Control redirect behavior
followRedirects: true

# Check only modified files in git
modifiedFilesOnly: false

# Respect .gitignore
useGitIgnore: true
When using environment variables in httpHeaders (like ${API_TOKEN}), create a .env file in your project root with the variable definitions.

​
Common Use Cases

​
Check a Single File

To check links in a specific file:
.linkspector.yml
files:
  - README.md
useGitIgnore: true

​
Check Only Modified Files

Useful in CI/CD to check only recently changed files:
.linkspector.yml
dirs:
  - ./docs
modifiedFilesOnly: true
useGitIgnore: true
The modifiedFilesOnly option requires Git to be installed and available in your system PATH.

​
Output in JSON Format

For integration with other tools or CI/CD pipelines: 
linkspector check --json
This outputs results in RDJSON format, which is compatible with reviewdog and other code review tools.

​
Troubleshooting

​
Puppeteer Installation Issues

If you encounter errors related to Puppeteer or Chrome, try: 
# Set Puppeteer to skip Chromium download during install
export PUPPETEER_SKIP_DOWNLOAD=true

# Then reinstall
npm install -g @umbrelladocs/linkspector

​
Too Many False Positives

Some websites block headless browsers. Use ignorePatterns to skip problematic URLs:
.linkspector.yml
ignorePatterns:
  - pattern: '^https://problematic-site\.com/.*$'

​
Rate Limiting

If you’re checking many links to the same domain, you might hit rate limits. Consider using custom headers or reducing the number of concurrent checks.

​
Next Steps

Now that you’ve run your first checks, explore more advanced features:

Configuration Guide

Learn about all available configuration options

GitHub Actions

Integrate Linkspector into your CI/CD pipeline

Command Reference

Explore all command-line options

AsciiDoc Support

Check links in AsciiDoc files

Build docs developers (and LLMs) love

Get started for freeTalk to us