Link Doctor

Link Doctor

Detects broken links in README.md, tutorials, blogs, and papers, then attempts to repair them.

Workflow

1. Scan All Markdown Files for Links

cd /Volumes/waku/github-维护/awesome/awesome-skills-repos && \
find . -name "*.md" -not -path "./.git/*" | head -20 && \
echo "---" && \
# Extract all GitHub links
grep -rhops "https://github.com/" --include="*.md" . | \
grep -oE "https://github\.com/[a-zA-Z0-9_-]+/[a-zA-Z0-9_.-]+" | \
sort -u | head -50

2. Check Links with curl (Batch)

cd /Volumes/waku/github-维护/awesome/awesome-skills-repos && \
python3 /dev/null | grep -oE "https://github\.com/[^ )\"\\']+" | sort -u',
        shell=True, capture_output=True, text=True
    )
    for url in result.stdout.strip().split('\n'):
        if url:
            # Normalize - remove trailing slashes, .git, etc.
            url = url.rstrip('/').replace('.git', '')
            github_urls.add(url)

urls = list(github_urls)
print(f"Total unique GitHub URLs to check: {len(urls)}")

def check_url(url):
    """Check a URL and return status"""
    try:
        result = subprocess.run(
            ['curl', '-s', '-o', '/dev/null', '-w', '%{http_code}', '-L', '--max-time', '10', url],
            capture_output=True, text=True, timeout=15
        )
        code = result.stdout.strip()
        return (url, code)
    except Exception as e:
        return (url, f"ERROR: {e}")

broken = []
working = []

with ThreadPoolExecutor(max_workers=10) as executor:
    futures = {executor.submit(check_url, url): url for url in urls[:100]}  # Check first 100
    
    for i, future in enumerate(as_completed(futures)):
        url, code = future.result()
        if code not in ['200', '301', '302']:
            broken.append((url, code))
            print(f"  BROKEN ({code}): {url}")
        else:
            working.append((url, code))
        
        if (i+1) % 20 == 0:
            print(f"Progress: {i+1}/{len(futures)}")

print(f"\n=== Results ===")
print(f"Working: {len(working)}")
print(f"Broken: {len(broken)}")

if broken:
    with open('/tmp/broken_links.json', 'w') as f:
        import json
        json.dump(broken, f, indent=2)
    print("Broken links saved to /tmp/broken_links.json")
PYEOF

3. Try to Repair Broken Links

python3  {new_url} ({best['stargazers_count']}★)")
                    continue
    except:
        pass
    
    # Try 2: Wayback Machine
    try:
        wm_url = f"https://web.archive.org/web/2024/{url}"
        result = subprocess.run(
            ['curl', '-s', '-o', '/dev/null', '-w', '%{http_code}', '--max-time', '5', wm_url],
            capture_output=True, text=True, timeout=8
        )
        if result.stdout.strip() == '200':
            repaired.append({
                'old': url,
                'new': wm_url,
                'reason': "Wayback Machine archive"
            })
            print(f"  ARCHIVED: {url}")
            print(f"    -> {wm_url}")
            continue
    except:
        pass
    
    # Unrepairable
    unrepairable.append({'url': url, 'code': code})
    print(f"  UNREPAIRABLE: {url} ({code})")

print(f"\n=== Summary ===")
print(f"Repaired: {len(repaired)}")
print(f"Unrepairable: {len(unrepairable)}")

if repaired:
    with open('/tmp/repaired_links.json', 'w') as f:
        json.dump(repaired, f, indent=2)

if unrepairable:
    with open('/tmp/unrepairable_links.json', 'w') as f:
        json.dump(unrepairable, f, indent=2)
PYEOF

4. Apply Repairs to Markdown Files

python3  {new_url}")
        except Exception as e:
            print(f"  Error fixing {filepath}: {e}")

print("\nAll repairs applied!")
PYEOF

5. Commit Changes

cd /Volumes/waku/github-维护/awesome/awesome-skills-repos && \
git status && \
echo "---" && \
read -p "Commit and push repairs? (y/n) " ans && \
if [ "$ans" = "y" ]; then \
    git add -A && \
    git commit -m "fix: repair broken links $(date +%Y-%m-%d)" && \
    git push && \
    echo "Done!"; \
fi

Notes

• Start with GitHub URLs (most common)
• Wayback Machine can rescue moved/deleted repos
• GitHub search API can find renamed repos
• Always review repairs before committing
• Run monthly to keep link health good

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vivy-yi
• Source: vivy-yi/awesome-skills
• License: MIT

Install and usage instructions live in the source repository linked above.