gone

gone

Fast, concurrent dead link detector for markdown files.

Scan your markdown files for broken links. gone finds all HTTP/HTTPS URLs, 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.

• Markdown-aware parsing. Finds links in [text](url), reference-style [text][ref], autolinks <url>, and HTML <a> tags. Knows to skip URLs inside 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
gone check

# Scan specific directory
gone check ./docs

# Output as JSON
gone check --format=json

# Launch interactive TUI
gone interactive

# Auto-fix redirect URLs
gone fix

Commands

gone check

Scan markdown files for dead links.

gone check [path] [flags]

Flags:

Link Status Types:

Examples:

# 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:

Controls:

gone fix

Automatically fix redirect URLs in markdown files.

gone fix [path] [flags]

Flags:

Examples:

# 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:

Setup Examples:

# 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:

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

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

  # Regular expressions
  regex:
    - ".*\\.(test|dev)$"
    - "192\\.168\\..*"

CLI Flags

CLI flags are additive with config file settings:

# These 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