# CLAUDE.md

## Overview

On-page SEO analyzer for single-page optimization: meta tags, headings, links, images, and Open Graph data.

## Quick Start

```bash
pip install -r scripts/requirements.txt
python scripts/page_analyzer.py --url https://example.com
```

## Scripts

| Script | Purpose |
|--------|---------|
| `page_analyzer.py` | Analyze on-page SEO elements |
| `base_client.py` | Shared utilities |

## Usage

```bash
# Full page analysis
python scripts/page_analyzer.py --url https://example.com

# JSON output
python scripts/page_analyzer.py --url https://example.com --json

# Analyze multiple pages
python scripts/page_analyzer.py --urls urls.txt
```

## Analysis Categories

### Meta Tags
- Title tag (length, keywords)
- Meta description (length, call-to-action)
- Canonical URL
- Robots meta tag

### Heading Structure
- H1 presence and count
- Heading hierarchy (H1→H6)
- Keyword placement in headings

### Links
- Internal link count
- External link count
- Broken links (4xx/5xx)
- Nofollow distribution

### Images
- Alt attribute presence
- Image file sizes
- Lazy loading implementation

### Open Graph / Social
- OG title, description, image
- Twitter Card tags
- Social sharing preview

## Output

```json
{
  "url": "https://example.com",
  "meta": {
    "title": "Page Title",
    "title_length": 55,
    "description": "...",
    "description_length": 150,
    "canonical": "https://example.com"
  },
  "headings": {
    "h1_count": 1,
    "h1_text": ["Main Heading"],
    "hierarchy_valid": true
  },
  "links": {
    "internal": 25,
    "external": 5,
    "broken": []
  },
  "issues": []
}
```

## Common Issues

| Issue | Severity | Recommendation |
|-------|----------|----------------|
| Missing H1 | High | Add single H1 tag |
| Title too long (>60) | Medium | Shorten to 50-60 chars |
| No meta description | High | Add compelling description |
| Images without alt | Medium | Add descriptive alt text |
| Multiple H1 tags | Medium | Use single H1 only |

## Dependencies

```
lxml>=5.1.0
beautifulsoup4>=4.12.0
requests>=2.31.0
python-dotenv>=1.0.0
rich>=13.7.0
```