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

## Notion Output (Required)

**IMPORTANT**: All audit reports MUST be saved to the OurDigital SEO Audit Log database.

### Database Configuration

| Field | Value |
|-------|-------|
| Database ID | `2c8581e5-8a1e-8035-880b-e38cefc2f3ef` |
| URL | https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef |

### Required Properties

| Property | Type | Description |
|----------|------|-------------|
| Issue | Title | Report title (Korean + date) |
| Site | URL | Audited website URL |
| Category | Select | Technical SEO, On-page SEO, Performance, Schema/Structured Data, Sitemap, Robots.txt, Content, Local SEO |
| Priority | Select | Critical, High, Medium, Low |
| Found Date | Date | Audit date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: [TYPE]-YYYYMMDD-NNN |

### Language Guidelines

- Report content in Korean (한국어)
- Keep technical English terms as-is (e.g., SEO Audit, Core Web Vitals, Schema Markup)
- URLs and code remain unchanged

### Example MCP Call

```bash
mcp-cli call notion/API-post-page '{"parent": {"database_id": "2c8581e5-8a1e-8035-880b-e38cefc2f3ef"}, "properties": {...}}'
```