Skip to main content
The check command is the main command in Linkspector. It scans your documentation files for hyperlinks and validates them according to your configuration.

​
Usage

linkspector check [options]

​
What It Does

When you run linkspector check, the tool:
  1. Loads configuration from .linkspector.yml (or a custom config file)
  2. Scans files based on your configured directories and file extensions
  3. Extracts all hyperlinks from Markdown and AsciiDoc files
  4. Validates each link:
    • HTTP/HTTPS links are checked for availability
    • File links are verified to exist
    • Header anchors are validated
    • Email links are skipped
  5. Reports broken or unreachable links
  6. Exits with code 0 if all links are valid, or code 1 if any links fail

​
Basic Example

linkspector check
This uses the default .linkspector.yml configuration file in your current directory.

​
Output Formats

​
Default Output (Console)

By default, Linkspector displays results in a human-readable format with a spinner showing progress: 
✨ Success: All hyperlinks in the specified files are valid.
When errors are found: 
docs/getting-started.md:42:15: 🚫 https://example.com/broken Status:404 Cannot reach link
docs/api/reference.md:108:23: 🚫 /path/to/missing.md Status:ENOENT File not found
💥 Error: Some hyperlinks in the specified files are invalid.

​
JSON Output

Use the -j or --json flag to output results in Reviewdog Diagnostic Format (RDJSON): 
linkspector check --json
Example JSON output: 
{
  "source": {
    "name": "linkspector",
    "url": "https://github.com/UmbrellaDocs/linkspector"
  },
  "severity": "ERROR",
  "diagnostics": [
    {
      "message": "Cannot reach https://example.com/broken Status: 404",
      "location": {
        "path": "docs/getting-started.md",
        "range": {
          "start": {
            "line": 42,
            "column": 15
          },
          "end": {
            "line": 42,
            "column": 45
          }
        }
      },
      "severity": "ERROR"
    }
  ]
}

​
Statistics Output

Use the -s or --showstat flag to display detailed statistics: 
linkspector check --showstat
Example output: 
💀📊 Linkspector check stats
┌───────────────────────────────┬────────┐
│ 🟰 Total files checked        │     12 │
├───────────────────────────────┼────────┤
│ 🔗 Total links checked        │    156 │
├───────────────────────────────┼────────┤
│ 🌐 Hyperlinks                 │     89 │
├───────────────────────────────┼────────┤
│ 📁 File and header links      │     62 │
├───────────────────────────────┼────────┤
│ ✉️  Email links (Skipped)      │      5 │
├───────────────────────────────┼────────┤
│ ✅ Working links              │    154 │
├───────────────────────────────┼────────┤
│ 🚫 Failed links               │      2 │
└───────────────────────────────┴────────┘

💥 Error: Some hyperlinks in the specified files are invalid.

​
Using a Custom Configuration File

linkspector check --config path/to/custom-config.yml
or using the short flag: 
linkspector check -c path/to/custom-config.yml
This is useful when:
  • You have multiple configuration files for different environments
  • Your config file is not in the current directory
  • You want to test different configurations

​
Combining Options

​
Check with Statistics

linkspector check --config .linkspector.prod.yml --showstat

​
Check with JSON Output

linkspector check --config .linkspector.yml --json > results.json

​
Error Handling

​
Configuration File Not Found

If no configuration file is found, Linkspector uses default settings: 
Configuration file not found. Using default configuration.
Default configuration:
  • Directories: ['.'] (current directory)
  • File extensions: ['md']
  • Use gitignore: true

​
Invalid Configuration

If your configuration file is invalid: 
💥 Error: Please check your configuration file.

​
Git Not Installed (when using modifiedFilesOnly)

If you enable modifiedFilesOnly but Git is not installed: 
Error: Git is not installed or not found in the system path.

​
No Modified Files

When using modifiedFilesOnly: true and no files have been modified: 
No modified files to check, skipping checking. To enable checking all files set modifiedFilesOnly: false and rerun the check.

​
Exit Codes

  • 0: All links are valid
  • 1: One or more links failed or an error occurred

​
Environment Variables

You can use environment variables in your configuration file. Linkspector will replace placeholders like ${VARIABLE_NAME} with the corresponding environment variable values. Example: 
# .linkspector.yml
baseUrl: ${BASE_URL}

BASE_URL=https://example.com linkspector check

Build docs developers (and LLMs) love

Get started for freeTalk to us