Skip to main content
Linkspector uses a configuration file named .linkspector.yml to customize its behavior. This file controls which files to check, how to handle links, and various other options.

​
Configuration File Location

By default, Linkspector looks for a configuration file named .linkspector.yml in the current directory where you run the command. You can specify a custom configuration file path using the -c or --config option: 
linkspector check -c /path/to/custom-config.yml

​
Default Configuration

If no configuration file is found, Linkspector displays the message: 
Configuration file not found. Using default configuration.
The default configuration is: 
dirs:
  - .
useGitIgnore: true
This configuration:
  • Checks all files in the current directory (.)
  • Respects .gitignore rules to exclude files and directories
If you are defining a custom configuration, you must include either the dirs or files section in the configuration file.

​
Configuration Options

Linkspector provides a comprehensive set of configuration options organized into several categories:

​
Files and Directories

Control which files and directories to check:
  • files - List of specific files to check
  • dirs - List of directories to search
  • excludedFiles - Files to exclude from checking
  • excludedDirs - Directories to exclude from checking
  • useGitIgnore - Respect .gitignore rules
  • modifiedFilesOnly - Check only git-modified files
Learn more about Files and Directories → Control how links are processed and filtered:
  • ignorePatterns - Regular expressions to skip certain URLs
  • replacementPatterns - Transform URLs before checking
  • baseUrl - Base URL for relative links
Learn more about Link Patterns →

​
HTTP Options

Configure HTTP request behavior:
  • aliveStatusCodes - Status codes considered as valid links
  • httpHeaders - Custom headers for specific URLs
  • followRedirects - Control redirect handling
Learn more about HTTP Options →

​
Basic Example

Here’s a simple configuration file to get started: 
dirs:
  - ./docs
  - ./README.md

excludedDirs:
  - ./node_modules

useGitIgnore: true

aliveStatusCodes:
  - 200
  - 201
  - 204
This configuration:
  • Checks all files in the ./docs directory and README.md
  • Excludes the node_modules directory
  • Respects .gitignore rules
  • Considers HTTP status codes 200, 201, and 204 as valid links

​
Next Steps

Files and Directories

Configure which files to check

Link Patterns

Control link processing

HTTP Options

Configure HTTP behavior

Advanced Configuration

See complete examples

Build docs developers (and LLMs) love

Get started for freeTalk to us