Skip to main content
Control which files and directories Linkspector checks for broken links using these configuration options.

​
Files to Check

The files section specifies individual files that Linkspector should check for broken links.
You must include either files or dirs (or both) in your configuration.

​
Configuration

files:
  - README.md
  - docs/getting-started.md
  - docs/api-reference.md

​
Behavior

  • Provide the full or relative paths to the files you want to check
  • Paths are relative to the current working directory
  • Supports Markdown (.md), AsciiDoc (.adoc), and other markup files
The dirs section lists directories where Linkspector should search for files to check.

​
Configuration

dirs:
  - ./
  - docs
  - content/blog

​
Behavior

  • Linkspector recursively searches all subdirectories
  • Use ./ or . to check the current directory
  • Paths are relative to the current working directory
  • All supported markup files in these directories will be checked
You can use both files and dirs together in the same configuration to check specific files and entire directories.

​
Excluded Files

The excludedFiles section allows you to specify files that should be excluded from link checking.

​
Configuration

excludedFiles:
  - ./check.md
  - docs/draft.md
  - CHANGELOG.md

​
Behavior

  • Files listed here will be skipped even if they’re in a directory specified in dirs
  • Useful for excluding drafts, templates, or files with known issues
  • Paths are relative to the current working directory

​
Example Use Case

dirs:
  - ./docs

excludedFiles:
  - ./docs/template.md
  - ./docs/draft-feature.md
This checks all files in ./docs except template.md and draft-feature.md.

​
Excluded Directories

The excludedDirs section lets you specify directories that should be excluded from link checking.

​
Configuration

excludedDirs:
  - ./lib
  - ./node_modules
  - ./vendor
  - docs/archive

​
Behavior

  • Directories listed here and all their contents will be skipped
  • Useful for excluding third-party code, build outputs, or archived content
  • Paths are relative to the current working directory

​
Example Use Case

dirs:
  - ./

excludedDirs:
  - ./node_modules
  - ./dist
  - ./.git
This checks all files in the current directory while excluding node_modules, dist, and .git directories.

​
Use GitIgnore

The useGitIgnore option tells Linkspector to respect the rules defined in your .gitignore file.

​
Configuration

useGitIgnore: true

​
Behavior

  • When set to true, Linkspector automatically excludes files and directories listed in .gitignore
  • When set to false, .gitignore rules are not applied
  • Default value: true (in the default configuration)

​
Example

If your .gitignore contains: 
node_modules/
.env
dist/
And your configuration is: 
dirs:
  - ./

useGitIgnore: true
Linkspector will automatically skip node_modules/, .env, and dist/ without you needing to add them to excludedDirs or excludedFiles.
Using useGitIgnore: true is recommended to avoid checking generated files and dependencies.

​
Check Modified Files Only

The modifiedFilesOnly option restricts link checking to files that have been modified in the last git commit.

​
Configuration

modifiedFilesOnly: true

​
Behavior

  • When set to true, Linkspector uses git to find modified files and only checks those
  • Only files changed in the last commit are checked
  • Useful in CI/CD pipelines to check only changed content
  • Requires git to be installed and available in your system path
This option requires git to be installed. If git is not found, Linkspector will throw an error.

​
Example Use Case

In a CI/CD pipeline where you only want to check links in files that were modified in the current pull request: 
dirs:
  - ./docs

modifiedFilesOnly: true
useGitIgnore: true
If no modified files are found in the list of files to check, Linkspector will skip link checking and exit with a message indicating no modified files were edited.

​
Complete Example

Here’s a comprehensive example combining all file and directory options: 
# Check specific files
files:
  - README.md
  - CONTRIBUTING.md

# Check these directories
dirs:
  - ./docs
  - ./content

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

# Exclude these directories
excludedDirs:
  - ./docs/archive
  - ./content/old

# Respect .gitignore rules
useGitIgnore: true

# Only check modified files (useful for CI/CD)
modifiedFilesOnly: false
This configuration:
  • Checks README.md and CONTRIBUTING.md explicitly
  • Searches the docs and content directories
  • Excludes specific template and draft files
  • Excludes archive and old content directories
  • Respects .gitignore rules
  • Checks all files (not just modified ones)

Build docs developers (and LLMs) love

Get started for freeTalk to us