Advanced Configuration

This page provides complete configuration examples and advanced use cases to help you get the most out of Linkspector.

Complete Sample Configuration

Here’s a comprehensive configuration file that demonstrates all available options:

# Files to check explicitly
files:
  - README.md
  - CONTRIBUTING.md
  - LICENSE.md

# Directories to search for files
dirs:
  - ./docs
  - ./content
  - ./blog

# Files to exclude from checking
excludedFiles:
  - ./docs/template.md
  - ./docs/draft.md
  - ./content/archive.md

# Directories to exclude from checking
excludedDirs:
  - ./node_modules
  - ./docs/archive
  - ./content/deprecated

# Base URL for resolving relative links
baseUrl: https://docs.example.com

# Patterns to ignore during link checking
ignorePatterns:
  # Ignore localhost and local IPs
  - pattern: '^https?://localhost.*$'
  - pattern: '^https?://127\\.0\\.0\\.1.*$'
  
  # Ignore FTP links
  - pattern: "^(ftp)://[^\\s/$?#]*\\.[^\\s]*$"
  
  # Ignore internal admin pages
  - pattern: '.*/admin/.*'
  - pattern: '.*/wp-admin/.*'
  
  # Ignore specific domains
  - pattern: '^https://internal.company.com/.*$'

# Patterns to transform URLs before checking
replacementPatterns:
  # Update old API URLs to new version
  - pattern: "(https?://api.example.com)/v1/"
    replacement: '$1/v2/'
  
  # Normalize user/post URLs
  - pattern: "(https?://example.com)/(\\w+)/(\\d+)"
    replacement: '$1/id/$3'

# Custom HTTP headers for authenticated endpoints
httpHeaders:
  # Production API
  - url:
      - https://api.example.com
      - https://api.example.com/v2
    headers:
      Authorization: Bearer ${PRODUCTION_TOKEN}
      X-API-Version: '2.0'
  
  # Internal documentation
  - url:
      - https://internal-docs.company.com
    headers:
      Authorization: Basic ${BASIC_AUTH}

# HTTP status codes considered as valid links
aliveStatusCodes:
  - 200  # OK
  - 201  # Created
  - 202  # Accepted
  - 204  # No Content

# Respect .gitignore rules
useGitIgnore: true

# Only check files modified in last commit
modifiedFilesOnly: false

# Follow HTTP redirects
followRedirects: true

Advanced Use Cases

CI/CD Pipeline Configuration

Optimized for continuous integration environments:

# Check only modified files for faster CI runs
modifiedFilesOnly: true

# Check documentation directories
dirs:
  - ./docs
  - ./README.md

# Exclude known issues
excludedDirs:
  - ./docs/archive

excludedFiles:
  - ./docs/known-issues.md

# Use git ignore to skip build artifacts
useGitIgnore: true

# Ignore localhost and development URLs
ignorePatterns:
  - pattern: '^https?://localhost.*$'
  - pattern: '^https?://127\\.0\\.0\\.1.*$'
  - pattern: '^https?://.*\\.local.*$'

# Follow redirects to check final destinations
followRedirects: true

# Accept standard success codes
aliveStatusCodes:
  - 200
  - 201
  - 204

Use modifiedFilesOnly: true in CI to only check links in changed files, significantly reducing build time.

Documentation Site with Authentication

For documentation that includes links to authenticated APIs:

# Check all documentation
dirs:
  - ./docs

baseUrl: https://docs.mycompany.com

# Authenticate to multiple services
httpHeaders:
  # Main API
  - url:
      - https://api.mycompany.com
    headers:
      Authorization: Bearer ${API_TOKEN}
      X-Client-ID: ${CLIENT_ID}
  
  # Admin panel
  - url:
      - https://admin.mycompany.com
    headers:
      Authorization: Basic ${ADMIN_CREDS}
  
  # Partner API
  - url:
      - https://partner-api.external.com
    headers:
      X-API-Key: ${PARTNER_KEY}

# Ignore staging and development environments
ignorePatterns:
  - pattern: '^https://staging\\.mycompany\\.com/.*$'
  - pattern: '^https://dev\\.mycompany\\.com/.*$'
  - pattern: '^https://.*\\.ngrok\\.io/.*$'

useGitIgnore: true
followRedirects: true

Multi-Language Documentation

For documentation sites with multiple language versions:

# Check all language directories
dirs:
  - ./docs/en
  - ./docs/es
  - ./docs/fr
  - ./docs/de
  - ./docs/ja

# Set base URL (update for each language if needed)
baseUrl: https://docs.example.com/en

# Exclude translation work-in-progress
excludedDirs:
  - ./docs/es/wip
  - ./docs/fr/wip

excludedFiles:
  - ./docs/ja/incomplete.md

# Ignore language-specific external resources
ignorePatterns:
  - pattern: '^https://translate\\.google\\.com/.*$'
  - pattern: '^https://.*\\.locize\\.com/.*$'

useGitIgnore: true

Strict Documentation Quality

For teams that want to enforce direct links (no redirects):

dirs:
  - ./docs

# DO NOT follow redirects - report them as errors
followRedirects: false

# Only accept direct successful responses
aliveStatusCodes:
  - 200
  - 204

# Fail on any deprecated URLs
ignorePatterns: []

# Ensure all relative links are tested
baseUrl: https://docs.example.com

useGitIgnore: true

With followRedirects: false, any redirected link will be reported as an error, helping maintain clean, direct URLs.

Open Source Project

Ideal configuration for open source projects:

# Check common documentation files
files:
  - README.md
  - CONTRIBUTING.md
  - CODE_OF_CONDUCT.md
  - SECURITY.md

# Check documentation directory
dirs:
  - ./docs

# Exclude generated files
excludedDirs:
  - ./node_modules
  - ./dist
  - ./build
  - ./.next

# Respect gitignore
useGitIgnore: true

# Ignore common development URLs
ignorePatterns:
  - pattern: '^https?://localhost.*$'
  - pattern: '^https?://127\\.0\\.0\\.1.*$'
  # Ignore example/placeholder domains
  - pattern: '^https?://example\\.(com|org|net).*$'

# Be lenient with status codes (some sites block bots)
aliveStatusCodes:
  - 200
  - 201
  - 202
  - 204
  - 206

# Follow redirects
followRedirects: true

Enterprise Documentation with VPN

For internal documentation that includes VPN-only resources:

dirs:
  - ./internal-docs
  - ./api-docs

baseUrl: https://docs.internal.company.com

# Authenticate to internal services
httpHeaders:
  - url:
      - https://wiki.internal.company.com
      - https://confluence.internal.company.com
    headers:
      Authorization: Bearer ${INTERNAL_TOKEN}
  
  - url:
      - https://api.internal.company.com
    headers:
      Authorization: Bearer ${API_TOKEN}
      X-Tenant-ID: ${TENANT_ID}

# Don't check external public sites (focus on internal)
ignorePatterns:
  - pattern: '^https?://(?!.*\\.internal\\.company\\.com).*$'

useGitIgnore: true
followRedirects: true

Best Practices

1. Use Environment Variables for Secrets

Always store sensitive information in environment variables:

httpHeaders:
  - url:
      - https://api.example.com
    headers:
      Authorization: ${API_TOKEN}  # Good - from environment
      # Authorization: Bearer abc123  # Bad - hardcoded secret

2. Leverage `.gitignore` Integration

Enable useGitIgnore to automatically exclude build artifacts:

useGitIgnore: true  # Automatically excludes node_modules, dist, etc.

3. Use `modifiedFilesOnly` in CI

Speed up CI builds by only checking changed files:

modifiedFilesOnly: true  # Only in CI configuration

4. Document Your Ignore Patterns

Add comments explaining why patterns are ignored:

ignorePatterns:
  # Localhost URLs (development only)
  - pattern: '^https?://localhost.*$'
  
  # Internal admin (requires special VPN access)
  - pattern: '.*/admin/.*'
  
  # Known third-party issue - ignore until fixed
  - pattern: '^https://problematic-site\\.com/.*$'

5. Test Configuration Locally First

Before committing configuration changes:

# Test with verbose output
linkspector check -s

# Test with specific config
linkspector check -c .linkspector.test.yml

6. Use Specific Status Codes

Be explicit about which status codes are acceptable:

# Explicit is better than implicit
aliveStatusCodes:
  - 200  # Standard success
  - 201  # Created (for API docs)
  - 204  # No content (for DELETE operations)

7. Organize Complex Configurations

Group related settings with comments:

# === File Selection ===
files:
  - README.md
dirs:
  - ./docs

# === Exclusions ===
excludedDirs:
  - ./node_modules

# === Link Processing ===
baseUrl: https://example.com
ignorePatterns:
  - pattern: '^https?://localhost.*$'

# === HTTP Configuration ===
aliveStatusCodes:
  - 200
followRedirects: true

Troubleshooting

Configuration Not Found

If you see “Configuration file not found”:

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

# Check current directory
ls -la .linkspector.yml

Too Many False Positives

If legitimate links are reported as broken:

Add them to ignorePatterns
Check if custom headers are needed in httpHeaders
Verify aliveStatusCodes includes the returned status code
Consider enabling followRedirects: true

Authentication Issues

If authenticated endpoints fail:

Verify environment variables are loaded:
```
echo $API_TOKEN
```
Check header format matches API requirements

Test with curl first:

curl -H "Authorization: Bearer $TOKEN" https://api.example.com

Performance Issues

If link checking is too slow:

Use modifiedFilesOnly: true in CI
Add more patterns to ignorePatterns
Use excludedDirs to skip large directories
Consider followRedirects: false to avoid redirect chains

Next Steps

Files and Directories

Learn about file selection options

Link Patterns

Master pattern matching

HTTP Options

Configure HTTP behavior

CLI Usage

See command-line options

Get Started

Commands

Configuration

Guides

Reference

Advanced Configuration

Complete Sample Configuration

Advanced Use Cases

CI/CD Pipeline Configuration

Documentation Site with Authentication

Multi-Language Documentation

Strict Documentation Quality

Open Source Project

Enterprise Documentation with VPN

Best Practices

1. Use Environment Variables for Secrets

2. Leverage `.gitignore` Integration

3. Use `modifiedFilesOnly` in CI

4. Document Your Ignore Patterns

5. Test Configuration Locally First

6. Use Specific Status Codes

7. Organize Complex Configurations

Troubleshooting

Configuration Not Found

Too Many False Positives

Authentication Issues

Performance Issues

Next Steps

Files and Directories

Link Patterns

HTTP Options

CLI Usage

Build docs developers (and LLMs) love

Get Started

Commands

Configuration

Guides

Reference

​Complete Sample Configuration

​Advanced Use Cases

​CI/CD Pipeline Configuration

​Documentation Site with Authentication

​Multi-Language Documentation

​Strict Documentation Quality

​Open Source Project

​Enterprise Documentation with VPN

​Best Practices

​1. Use Environment Variables for Secrets

​2. Leverage .gitignore Integration

​3. Use modifiedFilesOnly in CI

​4. Document Your Ignore Patterns

​5. Test Configuration Locally First

​6. Use Specific Status Codes

​7. Organize Complex Configurations

​Troubleshooting

​Configuration Not Found

​Too Many False Positives

​Authentication Issues

​Performance Issues

​Next Steps

Files and Directories

Link Patterns

HTTP Options

CLI Usage

Build docs developers (and LLMs) love

Complete Sample Configuration

Advanced Use Cases

CI/CD Pipeline Configuration

Documentation Site with Authentication

Multi-Language Documentation

Strict Documentation Quality

Open Source Project

Enterprise Documentation with VPN

Best Practices

1. Use Environment Variables for Secrets

2. Leverage `.gitignore` Integration

3. Use `modifiedFilesOnly` in CI

4. Document Your Ignore Patterns

5. Test Configuration Locally First

6. Use Specific Status Codes

7. Organize Complex Configurations

Troubleshooting

Configuration Not Found

Too Many False Positives

Authentication Issues

Performance Issues

Next Steps