A command-line tool to check for broken links in GitHub README files (or any markdown file accessible via URL).

• ✅ Checks all HTTP/HTTPS links in markdown files
• ✅ Detects markdown syntax [text](url) and plain URLs
• ✅ Detects HTML links <a href="url">text</a>
• ✅ Follows redirects and reports final status
• ✅ Appends broken links to output file with link text for easy reference
• ✅ Rate limiting to avoid overwhelming servers
• ✅ 10-second timeout per link

# Clone the repository
git clone https://github.com/yourusername/gh-linkcheck.git
cd gh-linkcheck

# Build the binary
go build -o gh-linkcheck

# (Optional) Install to your PATH
go install

gh-linkcheck https://raw.githubusercontent.com/user/repo/main/README.md

gh-linkcheck https://raw.githubusercontent.com/user/repo/main/README.md output/custom.md

Broken links are appended to the output file in the following format:

https://example.com/broken-page (404) - "Click here for docs"

https://another-broken.com/page (500) - "API Reference"

Each entry includes:

• The full URL
• HTTP status code (or 0 if the request failed)
• The visible link text from the markdown file

Entries are separated by 2 blank lines for readability.

The tool flags links with the following HTTP status codes:

• 403 - Forbidden
• 404 - Not Found
• 410 - Gone
• 500 - Internal Server Error
• 502 - Bad Gateway
• 503 - Service Unavailable
• 504 - Gateway Timeout

Successful redirects (301/302) that eventually return 200 are considered valid.

Check a popular project's README:

gh-linkcheck https://raw.githubusercontent.com/golang/go/master/README.md

Check with custom output location:

gh-linkcheck https://raw.githubusercontent.com/rust-lang/rust/master/README.md custom/broken.md

• The tool only checks public repositories (no authentication required)
• Each link is checked individually, even if the same URL appears multiple times
• Results are appended to the output file (not overwritten)
• The output directory is created automatically if it doesn't exist
• Rate limiting of 500ms between requests to be respectful to servers

MIT