HTTP Options

Linkspector provides several options to control HTTP request behavior, including status code handling, custom headers, and redirect management.

Alive Status Codes

The aliveStatusCodes option specifies which HTTP status codes should be considered as valid (“alive”) links.

Configuration

aliveStatusCodes:
  - 200
  - 201
  - 204

Behavior

Links returning any of these status codes are considered valid
By default, Linkspector considers standard success codes as valid
You can customize this list based on your specific requirements

Common Status Codes

Status Code	Meaning	Typical Use
200	OK	Standard successful response
201	Created	Resource successfully created
202	Accepted	Request accepted for processing
204	No Content	Successful request with no content
206	Partial Content	Partial resource returned

Example: Including Redirect Codes

aliveStatusCodes:
  - 200
  - 201
  - 204
  - 301  # Permanent redirect
  - 302  # Temporary redirect

Be careful when including redirect codes (3xx) in aliveStatusCodes if you also have followRedirects: true. The redirect will be followed, and the final destination’s status code will be used.

Example: API-Specific Codes

aliveStatusCodes:
  - 200
  - 201
  - 202
  - 204
  - 304  # Not Modified (useful for APIs with caching)

If aliveStatusCodes is not specified, Linkspector uses its default set of valid status codes.

HTTP Headers

The httpHeaders option allows you to specify custom HTTP headers for requests to specific URLs, which is useful for accessing authenticated or protected resources.

Configuration

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

Behavior

Each entry specifies a list of URLs and their corresponding headers
Multiple URLs can share the same set of headers
Headers are sent with every request to matching URLs
Supports environment variable interpolation using ${VARIABLE_NAME} syntax

Using Environment Variables

For sensitive values like API keys or authentication tokens, use environment variables:

1. Create a `.env` file

AUTH_TOKEN=abcdef123456
API_KEY=secret-key-value

2. Reference variables in configuration

httpHeaders:
  - url:
      - https://api.example.com
    headers:
      Authorization: ${AUTH_TOKEN}
      X-API-Key: ${API_KEY}

Never commit actual API keys or tokens to version control. Always use environment variables for sensitive values.

Common Use Cases

Basic Authentication

httpHeaders:
  - url:
      - https://protected.example.com
    headers:
      Authorization: Basic Zm9vOmJhcg==

The value Zm9vOmJhcg== is the Base64 encoding of username:password.

Bearer Token Authentication

httpHeaders:
  - url:
      - https://api.example.com
    headers:
      Authorization: Bearer ${ACCESS_TOKEN}

API Key Authentication

httpHeaders:
  - url:
      - https://api.service.com
    headers:
      X-API-Key: ${API_KEY}

Custom User Agent

httpHeaders:
  - url:
      - https://example.com
    headers:
      User-Agent: MyBot/1.0 (Link Checker)

Multiple URLs with Same Headers

httpHeaders:
  - url:
      - https://api.example.com
      - https://staging.example.com
      - https://dev.example.com
    headers:
      Authorization: ${AUTH_TOKEN}
      X-Environment: testing

Multiple Header Sets

You can define different headers for different URLs:

httpHeaders:
  # Production API
  - url:
      - https://api.production.com
    headers:
      Authorization: Bearer ${PROD_TOKEN}
      X-Environment: production
  
  # Staging API
  - url:
      - https://api.staging.com
    headers:
      Authorization: Bearer ${STAGING_TOKEN}
      X-Environment: staging
  
  # Public API (custom user agent only)
  - url:
      - https://public-api.example.com
    headers:
      User-Agent: Linkspector/1.0

Follow Redirects

The followRedirects option controls how Linkspector handles HTTP redirects (status codes like 301, 302, 307, 308).

Configuration

followRedirects: true  # Default

followRedirects: false

Behavior

When `followRedirects: true` (default)

Linkspector follows HTTP redirects to their final destination
The status of the link is determined by the final destination’s status code
If the final destination returns 200 OK, the original link is reported as “alive”
A message indicates that the link was redirected

Example:

Original link: http://example.com/old
Redirects to: http://example.com/new (200 OK)
Result: Link is reported as “alive” (200) with a redirect message

When `followRedirects: false`

Linkspector does NOT follow HTTP redirects
If a link returns a redirect status code, it’s reported as an error
The reported status code is the original redirect code (301, 302, etc.)
The error message indicates that the link redirected but following was disabled

Example:

Original link: http://example.com/old
Returns: 301 Moved Permanently
Result: Link is reported as “error” with status code 301

When to Use `followRedirects: false`

Consider disabling redirect following when:

You want to catch redirects: To identify and update old URLs in your documentation
Performance concerns: Following redirects adds latency to link checking
Redirect chains: To avoid potential infinite redirect loops
Documentation hygiene: To ensure all links point directly to their final destination

Example: Strict Link Checking

# Fail on any redirect to enforce direct links
followRedirects: false

aliveStatusCodes:
  - 200
  - 201
  - 204

With this configuration, any link that redirects (301, 302, etc.) will be reported as an error, forcing you to update the link to its final destination.

Example: Permissive Checking

# Follow redirects and accept them as valid
followRedirects: true

aliveStatusCodes:
  - 200
  - 201
  - 204
  - 301
  - 302

With this configuration, redirects are followed, and both the redirects themselves and their destinations are considered valid.

The default value is true, which is suitable for most use cases where you want to verify that links eventually resolve to valid content.

Complete Example

Here’s a comprehensive example combining all HTTP options:

# Define which status codes are considered valid
aliveStatusCodes:
  - 200  # OK
  - 201  # Created
  - 202  # Accepted
  - 204  # No Content

# Custom 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 site
  - url:
      - https://internal-docs.company.com
    headers:
      Authorization: Basic ${BASIC_AUTH_CREDS}
      X-Request-Source: linkspector
  
  # Third-party API
  - url:
      - https://external-api.service.com
    headers:
      X-API-Key: ${EXTERNAL_API_KEY}

# Follow redirects to check final destinations
followRedirects: true

# Other configuration...
dirs:
  - ./docs

With a corresponding .env file:

PRODUCTION_TOKEN=your-production-token-here
BASIC_AUTH_CREDS=dXNlcm5hbWU6cGFzc3dvcmQ=
EXTERNAL_API_KEY=your-api-key-here

This configuration:

Considers status codes 200, 201, 202, and 204 as valid
Sends appropriate authentication headers to different APIs
Uses environment variables for sensitive credentials
Follows redirects to verify final destinations
Checks all files in the ./docs directory

Get Started

Commands

Configuration

Guides

Reference

Alive Status Codes

Configuration

Behavior

Common Status Codes

Example: Including Redirect Codes

Example: API-Specific Codes

HTTP Headers

Configuration

Behavior

Using Environment Variables

1. Create a `.env` file

2. Reference variables in configuration

Common Use Cases

Basic Authentication

Bearer Token Authentication

API Key Authentication

Custom User Agent

Multiple URLs with Same Headers

Multiple Header Sets

Follow Redirects

Configuration

Behavior

When `followRedirects: true` (default)

When `followRedirects: false`

When to Use `followRedirects: false`

Example: Strict Link Checking

Example: Permissive Checking

Complete Example

Build docs developers (and LLMs) love

Get Started

Commands

Configuration

Guides

Reference

​Alive Status Codes

​Configuration

​Behavior

​Common Status Codes

​Example: Including Redirect Codes

​Example: API-Specific Codes

​HTTP Headers

​Configuration

​Behavior

​Using Environment Variables

​1. Create a .env file

​2. Reference variables in configuration

​Common Use Cases

​Basic Authentication

​Bearer Token Authentication

​API Key Authentication

​Custom User Agent

​Multiple URLs with Same Headers

​Multiple Header Sets

​Follow Redirects

​Configuration

​Behavior

​When followRedirects: true (default)

​When followRedirects: false

​When to Use followRedirects: false

​Example: Strict Link Checking

​Example: Permissive Checking

​Complete Example

Build docs developers (and LLMs) love

Alive Status Codes

Configuration

Behavior

Common Status Codes

Example: Including Redirect Codes

Example: API-Specific Codes

HTTP Headers

Configuration

Behavior

Using Environment Variables

1. Create a `.env` file

2. Reference variables in configuration

Common Use Cases

Basic Authentication

Bearer Token Authentication

API Key Authentication

Custom User Agent

Multiple URLs with Same Headers

Multiple Header Sets

Follow Redirects

Configuration

Behavior

When `followRedirects: true` (default)

When `followRedirects: false`

When to Use `followRedirects: false`

Example: Strict Link Checking

Example: Permissive Checking

Complete Example