gone

Fast, concurrent dead link detector for documentation files.

Scan your documentation files for broken links. gone finds all HTTP/HTTPS URLs in Markdown, JSON, YAML, TOML, and XML files, checks if they're still alive, and helps you fix the ones that aren't.

Here's a list of powerful features:

• Fast concurrent checking. Check hundreds of URLs at the same time. Configure the number of workers based on your network. Large documentation sites take seconds, not minutes.

• Interactive terminal UI. Watch progress in real-time. Navigate results with vim-style keys, filter by status, and explore issues without leaving your terminal. It's like htop for your links.

• Automatic redirect fixing. Found a redirect? gone fix updates your markdown to use the final URL. Preview changes first with --dry-run, confirm each file interactively, or let it fix everything with --yes.

• Smart deduplication. Same URL in 50 files? It gets checked once. Results map back to every occurrence. Less waiting, fewer rate limits.

• Flexible ignore rules. Skip localhost, staging environments, or that one URL that's always flaky. Use domains, glob patterns, or regex. Set them in .gonerc.yaml or pass them as flags.

• Multiple output formats. JSON, YAML, XML, JUnit, Markdown—pick your favorite. The format is auto-detected from the file extension, or set it explicitly with --format.

• Multi-format support. Scan Markdown, JSON, YAML, TOML, and XML files. Markdown parsing is format-aware: finds links in [text](url), reference-style [text][ref], autolinks <url>, and HTML <a> tags while skipping code blocks.

• CI/CD friendly. Exit code 0 means all good. Exit code 1 means dead links. JUnit output works with GitHub Actions, GitLab CI, Jenkins, and everything else.

Table of Contents

• Installation
• Quick Start
• Commands

• gone check

• gone interactive

• gone fix

• gone completion
• Configuration
• Output Formats
• CI/CD Integration
• Exit Codes
• Reference

• Commands Overview

• Flags Reference
• License

Installation

Go Install

go install github.com/leonardomso/gone@latest

Homebrew

brew install leonardomso/tap/gone

Build from Source

git clone https://github.com/leonardomso/gone.git
cd gone
go build

Download Binary

Download the latest release from the GitHub Releases page.

Quick Start

# Scan current directory (markdown files by default)
gone check

# Scan specific directory
gone check ./docs

# Scan multiple file types
gone check --types=md,json,yaml

# Output as JSON
gone check --format=json

# Launch interactive TUI
gone interactive

# Auto-fix redirect URLs
gone fix

Commands

gone check

Scan files for dead links.

gone check [path] [flags]

Flags:

# Scan markdown, JSON, and YAML files
gone check --types=md,json,yaml

# Scan with strict mode (fail on malformed files)
gone check --types=json --strict

# Scan with JSON output to stdout
gone check --format=json

# Write JUnit report for CI
gone check --output=report.junit.xml

# Show only dead links
gone check --dead

# Increase concurrency for faster scanning
gone check --concurrency=20

# Ignore specific domains
gone check --ignore-domain=localhost,example.com

gone interactive

Launch an interactive terminal UI with real-time progress.

gone interactive [path] [flags]

Flags:

gone fix

Automatically fix redirect URLs in files.

gone fix [path] [flags]

Flags:

# Interactive mode - prompt for each file
gone fix

# Preview what would be fixed
gone fix --dry-run

# Apply all fixes automatically
gone fix --yes

gone completion

Generate shell autocompletion scripts.

gone completion [shell]

Supported Shells:

# Bash (add to ~/.bashrc)
source <(gone completion bash)

# Zsh (add to ~/.zshrc)
source <(gone completion zsh)

# Fish
gone completion fish | source

Configuration

Config File

Create a .gonerc.yaml file in your project root:

# File types to scan (default: md)
types:
  - md
  - json
  - yaml
  - toml
  - xml

# Scanner settings
scan:
  # Include only files matching these glob patterns
  include:
    - "docs/**"
    - "README.md"
  # Exclude files matching these glob patterns
  exclude:
    - "node_modules/**"
    - "vendor/**"
    - ".git/**"

# Checker settings
check:
  concurrency: 50  # Number of concurrent workers
  timeout: 10      # Request timeout in seconds
  retries: 2       # Retry attempts for failed requests
  strict: false    # Fail on malformed files

# Output preferences
output:
  format: ""         # Default format (json, yaml, xml, junit, markdown)
  showAlive: false   # Show alive links in output
  showWarnings: true # Show warnings (redirects, blocked)
  showDead: true     # Show dead links
  showStats: false   # Show performance statistics

# Ignore rules
ignore:
  # Ignore entire domains (includes subdomains)
  domains:
    - localhost
    - example.com
    - staging.myapp.com

  # Glob patterns
  patterns:
    - "*.local/*"
    - "*/internal/*"

  # Regular expressions
  regex:
    - ".*\\.(test|dev)%%CODEBLOCK11%%quot;
    - "192\\.168\\..*"

Supported File Types

CLI Flags

CLI flags override config file settings:

# Override types from config
gone check --types=md,json

# Override concurrency
gone check --concurrency=100

# These ignore rules are combined with .gonerc.yaml settings
gone check --ignore-domain=api.example.com --ignore-pattern="*.internal/*"

Output Formats

JSON

gone check --format=json
# or
gone check --output=report.json

YAML

gone check --format=yaml
# or
gone check --output=report.yaml

JUnit XML (for CI/CD)

gone check --output=report.junit.xml

Markdown

gone check --format=markdown
# or
gone check --output=report.md

CI/CD Integration

GitHub Actions

name: Check Links

on:
  push:
    branches: [master]
  pull_request:
    branches: [master]
  schedule:
    - cron: '0 0 * * 0'  # Weekly

jobs:
  check-links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.24'

      - name: Install gone
        run: go install github.com/leonardomso/gone@latest

      - name: Check links
        run: gone check --output=report.junit.xml

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: link-report
          path: report.junit.xml

Exit Codes

Reference

Commands Overview

Flags Reference

License

MIT