Markdown Link Checker

{
  "hookConfig": {
    "hooks": {
      "postToolUse": {
        "script": "./.claude/hooks/markdown-link-checker.sh",
        "matchers": [
          "write",
          "edit"
        ]
      }
    }
  },
  "scriptContent": "#!/usr/bin/env bash\n\n# Read the tool input from stdin\nINPUT=$(cat)\nTOOL_NAME=$(echo \"$INPUT\" | jq -r '.tool_name')\nFILE_PATH=$(echo \"$INPUT\" | jq -r '.tool_input.file_path // .tool_input.path // \"\"')\n\nif [ -z \"$FILE_PATH\" ]; then\n  exit 0\nfi\n\n# Check if this is a markdown file\nif [[ \"$FILE_PATH\" == *.md ]] || [[ \"$FILE_PATH\" == *.mdx ]] || [[ \"$FILE_PATH\" == *.markdown ]]; then\n  echo \"🔗 Markdown Link Validation for: $(basename \"$FILE_PATH\")\" >&2\n  \n  # Initialize validation counters\n  ERRORS=0\n  WARNINGS=0\n  VALIDATIONS_PASSED=0\n  TOTAL_LINKS=0\n  EXTERNAL_LINKS=0\n  INTERNAL_LINKS=0\n  \n  # Function to report validation results\n  report_validation() {\n    local level=\"$1\"\n    local message=\"$2\"\n    \n    case \"$level\" in\n      \"ERROR\")\n        echo \"❌ ERROR: $message\" >&2\n        ERRORS=$((ERRORS + 1))\n        ;;\n      \"WARNING\")\n        echo \"⚠️ WARNING: $message\" >&2\n        WARNINGS=$((WARNINGS + 1))\n        ;;\n      \"PASS\")\n        echo \"✅ PASS: $message\" >&2\n        VALIDATIONS_PASSED=$((VALIDATIONS_PASSED + 1))\n        ;;\n      \"INFO\")\n        echo \"ℹ️ INFO: $message\" >&2\n        ;;\n    esac\n  }\n  \n  # Check if file exists and is readable\n  if [ ! -f \"$FILE_PATH\" ]; then\n    report_validation \"ERROR\" \"Markdown file not found: $FILE_PATH\"\n    exit 1\n  fi\n  \n  if [ ! -r \"$FILE_PATH\" ]; then\n    report_validation \"ERROR\" \"Markdown file is not readable: $FILE_PATH\"\n    exit 1\n  fi\n  \n  # Get file information\n  FILE_NAME=\"$(basename \"$FILE_PATH\")\"\n  FILE_DIR=\"$(dirname \"$FILE_PATH\")\"\n  FILE_SIZE=$(wc -c < \"$FILE_PATH\" 2>/dev/null || echo \"0\")\n  LINE_COUNT=$(wc -l < \"$FILE_PATH\" 2>/dev/null || echo \"0\")\n  \n  echo \"📊 Markdown file: $FILE_NAME ($(( FILE_SIZE / 1024 ))KB, $LINE_COUNT lines)\" >&2\n  \n  # 1. Extract All Links from Markdown\n  echo \"🔍 Extracting links from markdown...\" >&2\n  \n  # Create temporary files for link analysis\n  TEMP_LINKS=\"/tmp/markdown_links_$$\"\n  TEMP_IMAGES=\"/tmp/markdown_images_$$\"\n  TEMP_ANCHORS=\"/tmp/markdown_anchors_$$\"\n  \n  # Extract markdown links [text](url)\n  grep -oE '\\[([^\\]]+)\\]\\(([^)]+)\\)' \"$FILE_PATH\" | sed 's/\\[.*\\](\\(.*\\))/\\1/' > \"$TEMP_LINKS\" 2>/dev/null || true\n  \n  # Extract image links ![alt](url)\n  grep -oE '!\\[([^\\]]*)\\]\\(([^)]+)\\)' \"$FILE_PATH\" | sed 's/!\\[.*\\](\\(.*\\))/\\1/' > \"$TEMP_IMAGES\" 2>/dev/null || true\n  \n  # Extract reference-style links\n  grep -oE '\\[([^\\]]+)\\]\\[([^\\]]+)\\]' \"$FILE_PATH\" | sed 's/\\[.*\\]\\[\\(.*\\)\\]/\\1/' >> \"$TEMP_LINKS\" 2>/dev/null || true\n  \n  # Count total links\n  TOTAL_LINKS=$(cat \"$TEMP_LINKS\" \"$TEMP_IMAGES\" 2>/dev/null | wc -l || echo \"0\")\n  \n  if [ \"$TOTAL_LINKS\" -eq 0 ]; then\n    echo \"   📋 No links found in markdown file\" >&2\n    report_validation \"INFO\" \"No links to validate\"\n  else\n    echo \"   📊 Found $TOTAL_LINKS total links/images\" >&2\n  fi\n  \n  # 2. Validate External Links\n  echo \"🌐 Validating external links...\" >&2\n  \n  # Try using markdown-link-check if available\n  if command -v npx &> /dev/null; then\n    echo \"   🔍 Using markdown-link-check for comprehensive validation...\" >&2\n    \n    # Create a temporary config if none exists\n    CONFIG_FILE=\".markdown-link-check.json\"\n    TEMP_CONFIG=false\n    \n    if [ ! -f \"$CONFIG_FILE\" ]; then\n      TEMP_CONFIG=true\n      CONFIG_FILE=\"/tmp/markdown_link_config_$$\"\n      cat > \"$CONFIG_FILE\" << 'EOF'\n{\n  \"timeout\": \"30s\",\n  \"retryOn429\": true,\n  \"retryCount\": 3,\n  \"fallbackProtocols\": [\"http\", \"https\"],\n  \"ignorePatterns\": [\n    { \"pattern\": \"^http://localhost\" },\n    { \"pattern\": \"^https://localhost\" },\n    { \"pattern\": \"^http://127.0.0.1\" },\n    { \"pattern\": \"^#\" }\n  ]\n}\nEOF\n    fi\n    \n    MLC_OUTPUT_FILE=\"/tmp/mlc_output_$$\"\n    if timeout 60s npx markdown-link-check \"$FILE_PATH\" --config \"$CONFIG_FILE\" > \"$MLC_OUTPUT_FILE\" 2>&1; then\n      # Parse results\n      DEAD_LINKS=$(grep -c '✖' \"$MLC_OUTPUT_FILE\" 2>/dev/null || echo \"0\")\n      ALIVE_LINKS=$(grep -c '✓' \"$MLC_OUTPUT_FILE\" 2>/dev/null || echo \"0\")\n      \n      if [ \"$DEAD_LINKS\" -eq 0 ]; then\n        report_validation \"PASS\" \"All external links are valid ($ALIVE_LINKS checked)\"\n      else\n        report_validation \"ERROR\" \"Found $DEAD_LINKS dead external links\"\n        echo \"   📝 Dead links details:\" >&2\n        grep '✖' \"$MLC_OUTPUT_FILE\" | head -5 | while read line; do\n          echo \"     $line\" >&2\n        done\n      fi\n    else\n      # Fallback to basic URL validation\n      echo \"   ⚠️ markdown-link-check failed, using basic validation...\" >&2\n      \n      # Extract HTTP/HTTPS URLs\n      EXTERNAL_URLS=$(grep -oE 'https?://[^)]+' \"$TEMP_LINKS\" 2>/dev/null || true)\n      \n      if [ -n \"$EXTERNAL_URLS\" ]; then\n        EXTERNAL_COUNT=$(echo \"$EXTERNAL_URLS\" | wc -l)\n        echo \"   🌐 Found $EXTERNAL_COUNT external URLs to validate\" >&2\n        \n        # Basic URL validation using curl\n        if command -v curl &> /dev/null; then\n          EXTERNAL_ERRORS=0\n          echo \"$EXTERNAL_URLS\" | head -10 | while read -r url; do\n            if [ -n \"$url\" ]; then\n              if curl -s --head --max-time 10 \"$url\" >/dev/null 2>&1; then\n                echo \"     ✅ Valid: $url\" >&2\n              else\n                echo \"     ❌ Invalid: $url\" >&2\n                EXTERNAL_ERRORS=$((EXTERNAL_ERRORS + 1))\n              fi\n            fi\n          done\n        else\n          echo \"   ⚠️ curl not available for URL validation\" >&2\n        fi\n      else\n        echo \"   📋 No external URLs found\" >&2\n      fi\n    fi\n    \n    # Clean up temporary config if created\n    [ \"$TEMP_CONFIG\" = true ] && rm -f \"$CONFIG_FILE\"\n    rm -f \"$MLC_OUTPUT_FILE\"\n    \n  else\n    echo \"   ⚠️ npx not available, using basic link validation\" >&2\n  fi\n  \n  # 3. Validate Internal Links\n  echo \"📁 Validating internal links and references...\" >&2\n  \n  # Extract internal links (relative paths)\n  INTERNAL_URLS=$(cat \"$TEMP_LINKS\" \"$TEMP_IMAGES\" 2>/dev/null | grep -E '^\\./|^\\.\\./' || true)\n  ABSOLUTE_PATHS=$(cat \"$TEMP_LINKS\" \"$TEMP_IMAGES\" 2>/dev/null | grep -E '^/' || true)\n  \n  INTERNAL_ERRORS=0\n  \n  # Check relative path links\n  if [ -n \"$INTERNAL_URLS\" ]; then\n    echo \"   📂 Checking relative path links...\" >&2\n    \n    echo \"$INTERNAL_URLS\" | while read -r link; do\n      if [ -n \"$link\" ]; then\n        # Remove anchor if present\n        FILE_PART=$(echo \"$link\" | cut -d'#' -f1)\n        ANCHOR_PART=$(echo \"$link\" | cut -d'#' -f2)\n        \n        if [ -n \"$FILE_PART\" ]; then\n          # Resolve relative path\n          RESOLVED_PATH=\"$(cd \"$FILE_DIR\" && realpath \"$FILE_PART\" 2>/dev/null || echo \"$FILE_PART\")\"\n          \n          if [ -f \"$RESOLVED_PATH\" ] || [ -d \"$RESOLVED_PATH\" ]; then\n            echo \"     ✅ Valid: $link\" >&2\n          else\n            echo \"     ❌ Broken: $link (resolved to: $RESOLVED_PATH)\" >&2\n            INTERNAL_ERRORS=$((INTERNAL_ERRORS + 1))\n          fi\n        fi\n        \n        # Check anchor if present (simplified check)\n        if [ \"$link\" != \"$FILE_PART\" ] && [ -n \"$ANCHOR_PART\" ]; then\n          echo \"     ℹ️ Anchor found: #$ANCHOR_PART\" >&2\n        fi\n      fi\n    done\n  fi\n  \n  # Check absolute path links\n  if [ -n \"$ABSOLUTE_PATHS\" ]; then\n    echo \"   📁 Checking absolute path links...\" >&2\n    \n    echo \"$ABSOLUTE_PATHS\" | while read -r link; do\n      if [ -n \"$link\" ]; then\n        FILE_PART=$(echo \"$link\" | cut -d'#' -f1)\n        \n        if [ -f \"$FILE_PART\" ] || [ -d \"$FILE_PART\" ]; then\n          echo \"     ✅ Valid: $link\" >&2\n        else\n          echo \"     ❌ Broken: $link\" >&2\n          INTERNAL_ERRORS=$((INTERNAL_ERRORS + 1))\n        fi\n      fi\n    done\n  fi\n  \n  if [ \"$INTERNAL_ERRORS\" -eq 0 ]; then\n    report_validation \"PASS\" \"All internal links are valid\"\n  else\n    report_validation \"ERROR\" \"Found $INTERNAL_ERRORS broken internal links\"\n  fi\n  \n  # 4. Validate Image Links\n  echo \"🖼️ Validating image links...\" >&2\n  \n  IMAGE_COUNT=$(cat \"$TEMP_IMAGES\" 2>/dev/null | wc -l || echo \"0\")\n  \n  if [ \"$IMAGE_COUNT\" -gt 0 ]; then\n    echo \"   📊 Found $IMAGE_COUNT image links\" >&2\n    \n    IMAGE_ERRORS=0\n    \n    cat \"$TEMP_IMAGES\" | while read -r img_link; do\n      if [ -n \"$img_link\" ]; then\n        if [[ \"$img_link\" == http* ]]; then\n          echo \"     🌐 External image: $img_link\" >&2\n        else\n          # Local image file\n          if [[ \"$img_link\" == /* ]]; then\n            IMG_PATH=\"$img_link\"\n          else\n            IMG_PATH=\"$FILE_DIR/$img_link\"\n          fi\n          \n          if [ -f \"$IMG_PATH\" ]; then\n            echo \"     ✅ Valid image: $img_link\" >&2\n          else\n            echo \"     ❌ Missing image: $img_link\" >&2\n            IMAGE_ERRORS=$((IMAGE_ERRORS + 1))\n          fi\n        fi\n      fi\n    done\n    \n    if [ \"$IMAGE_ERRORS\" -eq 0 ]; then\n      report_validation \"PASS\" \"All local images found\"\n    else\n      report_validation \"ERROR\" \"$IMAGE_ERRORS local images missing\"\n    fi\n  else\n    echo \"   📋 No image links found\" >&2\n  fi\n  \n  # 5. Validate Internal Anchors\n  echo \"⚓ Validating document anchors...\" >&2\n  \n  # Extract anchor-only links (starting with #)\n  ANCHOR_LINKS=$(cat \"$TEMP_LINKS\" | grep '^#' 2>/dev/null || true)\n  \n  if [ -n \"$ANCHOR_LINKS\" ]; then\n    echo \"   🔗 Found anchor links to validate\" >&2\n    \n    # Extract headers from markdown to validate anchors\n    HEADERS_FILE=\"/tmp/markdown_headers_$$\"\n    grep -E '^#{1,6} ' \"$FILE_PATH\" | sed 's/^#* *//' | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9 -]//g' | sed 's/ /-/g' > \"$HEADERS_FILE\" 2>/dev/null || true\n    \n    ANCHOR_ERRORS=0\n    \n    echo \"$ANCHOR_LINKS\" | while read -r anchor; do\n      if [ -n \"$anchor\" ]; then\n        CLEAN_ANCHOR=$(echo \"$anchor\" | sed 's/^#//' | tr '[:upper:]' '[:lower:]')\n        \n        if grep -q \"^$CLEAN_ANCHOR$\" \"$HEADERS_FILE\" 2>/dev/null; then\n          echo \"     ✅ Valid anchor: $anchor\" >&2\n        else\n          echo \"     ❌ Invalid anchor: $anchor\" >&2\n          ANCHOR_ERRORS=$((ANCHOR_ERRORS + 1))\n        fi\n      fi\n    done\n    \n    rm -f \"$HEADERS_FILE\"\n    \n    if [ \"$ANCHOR_ERRORS\" -eq 0 ]; then\n      report_validation \"PASS\" \"All document anchors valid\"\n    else\n      report_validation \"ERROR\" \"$ANCHOR_ERRORS invalid document anchors\"\n    fi\n  else\n    echo \"   📋 No document anchors found\" >&2\n  fi\n  \n  # 6. Markdown Quality Checks\n  echo \"📝 Markdown quality and accessibility checks...\" >&2\n  \n  # Check for alt text in images\n  IMAGES_WITHOUT_ALT=$(grep -c '!\\[\\](' \"$FILE_PATH\" 2>/dev/null || echo \"0\")\n  \n  if [ \"$IMAGES_WITHOUT_ALT\" -gt 0 ]; then\n    report_validation \"WARNING\" \"$IMAGES_WITHOUT_ALT images missing alt text for accessibility\"\n  else\n    if [ \"$IMAGE_COUNT\" -gt 0 ]; then\n      report_validation \"PASS\" \"All images have alt text\"\n    fi\n  fi\n  \n  # Check for bare URLs (not wrapped in markdown links)\n  BARE_URLS=$(grep -oE 'https?://[^\\s\\)\\]]+' \"$FILE_PATH\" | grep -v '](http' | head -5 | wc -l || echo \"0\")\n  \n  if [ \"$BARE_URLS\" -gt 0 ]; then\n    report_validation \"WARNING\" \"Found $BARE_URLS bare URLs - consider wrapping in markdown links\"\n  fi\n  \n  # 7. Generate Validation Summary\n  echo \"\" >&2\n  echo \"📋 Markdown Link Validation Summary:\" >&2\n  echo \"===================================\" >&2\n  echo \"   📄 File: $FILE_NAME\" >&2\n  echo \"   📏 Size: $(( FILE_SIZE / 1024 ))KB, $LINE_COUNT lines\" >&2\n  echo \"   🔗 Total links: $TOTAL_LINKS\" >&2\n  echo \"   🖼️ Images: $IMAGE_COUNT\" >&2\n  echo \"   ✅ Validations passed: $VALIDATIONS_PASSED\" >&2\n  echo \"   ⚠️ Warnings: $WARNINGS\" >&2\n  echo \"   ❌ Errors: $ERRORS\" >&2\n  \n  if [ \"$ERRORS\" -eq 0 ]; then\n    if [ \"$WARNINGS\" -eq 0 ]; then\n      echo \"   🎉 Status: EXCELLENT - All links are valid and accessible\" >&2\n    else\n      echo \"   ✅ Status: GOOD - Links are valid with minor accessibility recommendations\" >&2\n    fi\n  else\n    echo \"   ❌ Status: ERRORS - Found broken links that must be fixed\" >&2\n  fi\n  \n  echo \"\" >&2\n  echo \"💡 Markdown Link Best Practices:\" >&2\n  echo \"   • Use descriptive link text instead of 'click here'\" >&2\n  echo \"   • Add alt text to all images for accessibility\" >&2\n  echo \"   • Use relative paths for internal documentation\" >&2\n  echo \"   • Validate external links regularly\" >&2\n  echo \"   • Keep anchor links synchronized with headers\" >&2\n  echo \"   • Consider using reference-style links for readability\" >&2\n  \n  # Clean up temporary files\n  rm -f \"$TEMP_LINKS\" \"$TEMP_IMAGES\" \"$TEMP_ANCHORS\"\n  \n  # Exit with error if there are critical link issues\n  if [ \"$ERRORS\" -gt 0 ]; then\n    echo \"⚠️ Markdown link validation completed with errors\" >&2\n    exit 1\n  fi\n  \nelse\n  # Not a markdown file\n  exit 0\nfi\n\nexit 0"
}