Skip to main content
Linkspector provides multiple output formats to suit different workflows: CSV-style console output for quick debugging, RDJSON for CI/CD integration, and detailed statistics for comprehensive reporting.

​
CSV-Style Error Output

When Linkspector finds broken links in default mode, it outputs results in a CSV-style format to the console. This format is designed for quick human readability and easy parsing.

​
Format Structure

filename:line_number:column: status emoji link Status:status_code error_message

​
Example Output

REDISTRIBUTED.md:186:1: 🚫 https://unlicense.org/ Status:null net::ERR_SSL_VERSION_OR_CIPHER_MISMATCH at https://unlicense.org/
README.md:45:12: 🚫 https://example.com/broken Status:404 Cannot reach link
💥 Error: Some hyperlinks in the specified files are invalid.

​
Fields Explained

  • filename - Relative path to the file containing the broken link
  • line_number - Line number where the link appears (1-based)
  • column - Column position where the link starts (1-based)
  • status emoji - Visual indicator (🚫 for errors, ✨ for success)
  • link - The actual URL that was checked
  • status_code - HTTP status code (or null if not applicable)
  • error_message - Descriptive error message explaining the failure

​
Success Output

When all links are valid: 
✨ Success: All hyperlinks in the specified files are valid.

​
JSON/RDJSON Output

Linkspector supports JSON output in the RDJSON (Reviewdog Diagnostic Format) format, making it ideal for CI/CD integration and automated tooling.

​
Enabling JSON Output

Use the --json or -j flag: 
linkspector check --json

​
RDJSON Structure

{
  "source": {
    "name": "linkspector",
    "url": "https://github.com/UmbrellaDocs/linkspector"
  },
  "severity": "ERROR",
  "diagnostics": [
    {
      "message": "Cannot reach https://example.com/broken Status: 404 Cannot reach link",
      "location": {
        "path": "README.md",
        "range": {
          "start": {
            "line": 45,
            "column": 12
          },
          "end": {
            "line": 45,
            "column": 45
          }
        }
      },
      "severity": "ERROR"
    }
  ]
}

​
Empty RDJSON Output

When no broken links are found: 
{
  "source": {
    "name": "linkspector",
    "url": "https://github.com/UmbrellaDocs/linkspector"
  },
  "severity": "INFO",
  "diagnostics": []
}

​
Diagnostic Fields

Each diagnostic entry contains:
  • message - Error description including the URL, status code, and error details
  • location.path - File path relative to the current directory
  • location.range.start - Starting position (line and column)
  • location.range.end - Ending position (line and column)
  • severity - Always "ERROR" for broken links
Line and column numbers in RDJSON are 1-based, matching most editor conventions.

​
RDJSON Validation Process

Linkspector automatically validates and fixes RDJSON output using the @umbrelladocs/rdformat-validator package to ensure compliance with the RDJSON specification.

​
Validation Levels

The validation process uses two fix levels:
  1. Basic Validation - Applied first, fixes common formatting issues
    • Ensures all required fields are present
    • Validates line and column numbers are positive integers
    • Corrects field types and structure
  2. Aggressive Validation - Applied if basic validation fails
    • Attempts more extensive corrections
    • Fills in missing data with default values
    • Restructures malformed diagnostics

​
Automatic Fixes

Common automatic fixes include:
  • Ensuring line and column numbers are at least 1
  • Adding missing required fields with sensible defaults
  • Correcting invalid severity levels
  • Fixing malformed range objects

​
Validation Messages

When fixes are applied, validation messages are written to stderr: 
# RDJSON Validation: RDJSON validated and 3 fixes applied
# Applied fixes: 3

​
Validation Failure Fallback

If validation completely fails, Linkspector outputs an empty but valid RDJSON structure: 
# RDJSON Validation Error: diagnostics[0].location.range.start.line: must be >= 1
The fallback ensures CI/CD pipelines receive valid JSON even in edge cases.

​
Statistics Output

Display comprehensive link checking statistics with the --showstat or -s flag.

​
Enabling Statistics

linkspector check --showstat
The --showstat and --json options cannot be used together.

​
Statistics Table

💀📊 Linkspector check stats
┌───────────────────────────────┬────────┐
│ 🟰 Total files checked        │     12 │
├───────────────────────────────┼────────┤
│ 🔗 Total links checked        │    245 │
├───────────────────────────────┼────────┤
│ 🌐 Hyperlinks                 │    198 │
├───────────────────────────────┼────────┤
│ 📁 File and header links      │     42 │
├───────────────────────────────┼────────┤
│ ✉️  Email links (Skipped)      │      5 │
├───────────────────────────────┼────────┤
│ ✅ Working links              │    243 │
├───────────────────────────────┼────────┤
│ 🚫 Failed links               │      2 │
└───────────────────────────────┴────────┘

​
Statistics Fields

  • Total files checked - Number of files processed
  • Total links checked - Total unique links found across all files
  • Hyperlinks - Links starting with http:// or https://
  • File and header links - Relative file paths, anchors, and hash links
  • Email links - Links starting with mailto: (automatically skipped)
  • Working links - Links with status alive or assumed alive
  • Failed links - Links with status error
Email links are automatically skipped and not counted in working or failed totals.

​
Combining Output Formats

Different output formats serve different purposes:

CSV Output

Best for: Quick debugging and local developmentUse when you need immediate visual feedback on broken links.

RDJSON Output

Best for: CI/CD pipelines and automationUse with tools like Reviewdog or custom scripts for automated checking.

Statistics

Best for: Reporting and documentation health metricsUse for periodic audits and tracking link health over time.

​
Exit Codes

Linkspector uses standard exit codes to indicate success or failure:
  • Exit 0 - All links are valid
  • Exit 1 - One or more broken links found, or configuration error
This makes it easy to integrate into scripts and CI/CD pipelines: 
linkspector check || echo "Build failed due to broken links"

Build docs developers (and LLMs) love

Get started for freeTalk to us