Slinky Link Checker

Validate external links across your repository. Ships as a self-contained GitHub Action (Docker) and a CLI.

Quick start (GitHub Action)

Add a workflow:

name: Slinky
on:
  pull_request:
    branches: [ main ]
jobs:
  slinky:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write  # Only needed if comment-pr is enabled
    steps:
      - uses: actions/checkout@v4
      - name: Run Slinky
        uses: LukeHagar/slinky@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # Required for PR comments
        with:
          targets: "docs/,README.md,**/*.md"
          # comment-pr: true  # Optional: post results as PR comment (default: true)

Note: The GITHUB_TOKEN is automatically provided by GitHub Actions via secrets.GITHUB_TOKEN and is only required for PR comment functionality. Core link checking works without it. If you disable PR comments (comment-pr: false), you can remove the pull-requests: write permission and the GITHUB_TOKEN env variable.

Inputs

• targets: Comma-separated paths and patterns to scan. Can be directories, files, or glob patterns (e.g. docs/,api-specs/**/*.yaml,README.md). Default: **/*
• concurrency: Max concurrent requests. Default: 16
• timeout: HTTP timeout seconds. Default: 10
• json-out: Optional JSON results path. Default: results.json
• md-out: Optional Markdown report path. Default: results.md
• repo-blob-base: Override GitHub blob base URL (https://github.com/<owner>/<repo>/blob/<sha>). Auto-detected in Actions.
• fail-on-failures: Fail job on any broken links. Default: true
• comment-pr: Post Markdown as a PR comment when applicable. Default: true
• step-summary: Append report to the job summary. Default: true
• watch: Watch for file changes and automatically re-scan (CLI only). Default: false

Output links in PRs

When running on PRs, Slinky auto-links files using the PR head commit. You can override with repo-blob-base.

CLI

Install (from source):

go build -o slinky ./

Usage:

# Headless: provide one or more targets (files, dirs, or globs)
slinky check **/*
slinky check ./docs/**/* ./markdown/**/*

# TUI mode: same targets
slinky run **/*

# Watch mode: automatically re-scan on file changes
slinky run --watch **/*

Notes:

• Targets can be files, directories, or doublestar globs. Multiple targets are allowed.
• If no targets are provided, the default is **/* relative to the current working directory.
• Watch mode monitors file changes and automatically re-scans when files are modified.

Watch Mode

Watch mode provides real-time link checking by monitoring file changes and automatically re-scanning when files are modified. This is particularly useful during development when you want to ensure links remain valid as you edit files.

Features:

• Automatic Re-scanning: Detects file changes and triggers new scans automatically
• Sequential Processing: Completes file scanning before starting URL checking for accurate counts
• Real-time Updates: Shows live progress as files are scanned and URLs are checked
• Configuration Monitoring: Watches .slinkignore files and re-scans when configuration changes
• Clean State Management: Each re-scan starts with a fresh state and accurate file counts

Usage:

# Watch all files in current directory
slinky run --watch

# Watch specific directories or files
slinky run --watch docs/ README.md

# Watch with glob patterns
slinky run --watch "**/*.md" "**/*.yaml"

Controls:

• q or Ctrl+C: Quit watch mode
• f: Toggle display of failed links only

How it works:

1. Initial Scan: Performs a complete scan of all target files
2. File Monitoring: Watches for changes to files matching the target patterns
3. Configuration Monitoring: Also watches .slinkignore files for configuration changes
4. Automatic Re-scan: When changes are detected, cancels the current scan and starts a fresh one
5. Clean Restart: Each re-scan resets counters and provides accurate file counts

Notes

• Respects .gitignore.
• Skips likely binary files and files > 2 MiB.
• Uses a browser-like User-Agent to reduce false negatives.

.slinkignore

Place a .slinkignore file at the repository root to exclude paths and/or specific URLs from scanning and reporting. The format is JSON with two optional arrays:

{
  "ignorePaths": [
    "**/vendor/**",
    "**/*.bak"
  ],
  "ignoreURLs": [
    "https://example.com/this/path/does/not/exist",
    "*localhost:*",
    "*internal.example.com*"
  ]
}

• ignorePaths: gitignore-style patterns evaluated against repository-relative paths (uses doublestar **).
• ignoreURLs: patterns applied to the full URL string. Supports exact matches, substring contains, and doublestar-style wildcard matches.

Examples:

• Ignore generated folders: "**/dist/**", backups: "**/*.bak".
• Ignore known example or placeholder links: "*example.com*", "https://example.com/foo".