berrypod/docs/plans/seo-enhancements.md

# SEO Enhancements

Status: Planned

## Vision

Comprehensive SEO tooling that rivals best-in-class WordPress plugins (Yoast, RankMath, AIOSEO) while staying true to Berrypod's principles: simple, non-overwhelming, and actually useful for small shop owners.

## Current State

Already implemented:
- Meta title/description (per custom page, auto-generated elsewhere)
- Open Graph and Twitter card tags
- Canonical URLs
- Dynamic XML sitemap (products, pages, categories)
- Dynamic robots.txt
- Product JSON-LD schema (name, price, availability)
- Breadcrumb JSON-LD schema
- Basic Organization JSON-LD
- Editable slugs (products, custom pages)
- Image alt text (editable in media library)
- URL redirects with 404 monitoring
- Responsive images with proper dimensions

## Gaps

### Tier 1: Quick Wins (High Impact, Low Effort)

| Gap | Impact | Effort |
|-----|--------|--------|
| Per-page noindex/nofollow | High | Low |
| Meta description for system pages | Medium | Low |
| Enhanced Organization schema | Medium | Low |
| Image sitemap | Medium | Low |

### Tier 2: Editor Experience (High Impact, Medium Effort)

| Gap | Impact | Effort |
|-----|--------|--------|
| SEO preview panel (Google/social) | High | Medium |
| Focus keyword per page | High | Medium |
| SEO score/checklist | High | Medium |
| Description length indicator | Medium | Low |

### Tier 3: Advanced Schema (Medium Impact, Medium Effort)

| Gap | Impact | Effort |
|-----|--------|--------|
| FAQ schema | Medium | Medium |
| Review/Rating schema | Medium | Medium (needs reviews feature) |
| LocalBusiness schema option | Low | Low |
| Video schema for embeds | Low | Medium |

### Tier 4: Analytics & Insights (Medium Impact, High Effort)

| Gap | Impact | Effort |
|-----|--------|--------|
| Search Console integration | High | High |
| Core Web Vitals monitoring | Medium | Medium |
| Keyword rank tracking | Low | High |

## Implementation Plan

### Phase 1: Per-Page SEO Controls (2h)

Add noindex/nofollow controls and meta description editing for all page types.

**Data model changes:**

```elixir
# Add to pages table
:meta_robots, :string, default: "index, follow"

# Add to settings (for default behaviour)
:default_meta_robots, :string, default: "index, follow"
```

**Tasks:**
1. Add `meta_robots` field to Pages schema
2. Add meta robots dropdown to settings editor (custom pages)
3. Add meta robots to shop_root.html.heex
4. Add system page meta description editing (store in Settings as JSON)

### Phase 2: Enhanced Schema (2h)

Improve existing schema and add Organization details.

**Data model changes:**

```elixir
# Add to settings
:business_type, :string  # "Organization" | "LocalBusiness" | "OnlineStore"
:business_phone, :string
:business_email, :string
:business_address, :map  # street, city, region, postal_code, country
:social_profiles, {:array, :map}  # [{platform, url}, ...]
```

**Tasks:**
1. Add business info fields to Settings
2. Add business info section to admin settings page
3. Enhance Organization JSON-LD with logo, contact, social profiles
4. Add LocalBusiness variant when address is provided
5. Add social profile links to schema (sameAs property)

### Phase 3: Image Sitemap (1h)

Add image entries to XML sitemap.

**Tasks:**
1. Update sitemap controller to include `<image:image>` entries
2. Add image namespace to sitemap XML
3. Include product images, page hero images, category images
4. Add image title and caption from alt text

### Phase 4: SEO Preview Panel (4h)

Live preview of how the page will appear in Google search results and social shares.

**UI location:** Settings editor panel (or new "SEO" section in Page tab after editor reorg)

**Preview types:**
1. **Google Search preview** — title (blue link), URL (green), description (grey)
2. **Social card preview** — OG image, title, description in card format

**Tasks:**
1. Create SEO preview component
2. Add Google search result mockup (title truncation at ~60 chars, desc at ~160)
3. Add social card mockup (Facebook/Twitter style)
4. Live-update previews as user types
5. Show character counts with colour indicators (green/yellow/red)
6. Pull in actual OG image if set

### Phase 5: Focus Keyword & SEO Score (4h)

Per-page focus keyword with SEO checklist scoring.

**Data model:**

```elixir
# Add to pages table
:focus_keyword, :string
```

**SEO checklist items:**
- [ ] Focus keyword in title
- [ ] Focus keyword in meta description
- [ ] Focus keyword in first paragraph
- [ ] Focus keyword in URL slug
- [ ] Meta description length (120-160 chars)
- [ ] Title length (50-60 chars)
- [ ] At least one image with alt text
- [ ] Internal links present
- [ ] External links present (optional)

**Score calculation:**
- Each checked item = points
- Display as percentage or traffic light (red/yellow/green)
- Show specific recommendations for unchecked items

**Tasks:**
1. Add focus_keyword field to Pages schema
2. Add focus keyword input to settings editor
3. Create SEO analysis module (pure functions, no side effects)
4. Create SEO checklist component
5. Integrate checklist into editor panel
6. Add helpful tooltips explaining each check

### Phase 6: FAQ Schema (2h)

Allow adding FAQ blocks that generate FAQPage schema.

**Approach:** New "FAQ" block type in page builder that:
- Renders as expandable accordion on frontend
- Generates FAQPage JSON-LD schema
- Supports multiple Q&A pairs

**Tasks:**
1. Create FAQ block type in page builder
2. Add FAQ block editor (question + answer pairs)
3. Render accordion UI on frontend
4. Generate FAQPage schema from block content
5. Add to allowed blocks for relevant page types

### Phase 7: Search Console Integration (6h)

OAuth connection to Google Search Console for insights.

**Features:**
- Connect/disconnect GSC account
- Show top queries driving traffic
- Show pages with impressions/clicks
- Show crawl errors
- Show Core Web Vitals summary

**Tasks:**
1. Set up Google OAuth credentials
2. Create GSC OAuth flow (connect button, callback, token storage)
3. Create GSC API client module
4. Create GSC dashboard in admin
5. Show top queries with clicks/impressions/CTR/position
6. Show indexed pages status
7. Cache API responses (refresh daily)

## Task Breakdown

| # | Task | Phase | Est | Status |
|---|------|-------|-----|--------|
| 1 | Add meta_robots field to Pages | 1 | 30m | planned |
| 2 | Add meta robots UI to settings editor | 1 | 30m | planned |
| 3 | Render meta robots in shop_root | 1 | 15m | planned |
| 4 | System page meta descriptions in Settings | 1 | 45m | planned |
| 5 | Add business info fields to Settings | 2 | 30m | planned |
| 6 | Business info admin UI | 2 | 45m | planned |
| 7 | Enhanced Organization JSON-LD | 2 | 30m | planned |
| 8 | LocalBusiness schema variant | 2 | 15m | planned |
| 9 | Image sitemap entries | 3 | 1h | planned |
| 10 | SEO preview component (Google) | 4 | 1.5h | planned |
| 11 | SEO preview component (Social) | 4 | 1h | planned |
| 12 | Character count indicators | 4 | 30m | planned |
| 13 | Integrate previews into editor | 4 | 1h | planned |
| 14 | Add focus_keyword field | 5 | 15m | planned |
| 15 | Focus keyword UI | 5 | 30m | planned |
| 16 | SEO analysis module | 5 | 1.5h | planned |
| 17 | SEO checklist component | 5 | 1h | planned |
| 18 | Integrate checklist into editor | 5 | 45m | planned |
| 19 | FAQ block type | 6 | 1h | planned |
| 20 | FAQ accordion frontend | 6 | 30m | planned |
| 21 | FAQ JSON-LD schema | 6 | 30m | planned |
| 22 | Google OAuth setup | 7 | 1h | planned |
| 23 | GSC OAuth flow | 7 | 1.5h | planned |
| 24 | GSC API client | 7 | 1.5h | planned |
| 25 | GSC dashboard UI | 7 | 2h | planned |

**Total estimate: ~21h**

## Suggested Implementation Order

1. **Phase 1** (2h) — Quick wins, immediate value
2. **Phase 3** (1h) — Image sitemap, easy win
3. **Phase 2** (2h) — Enhanced schema, improves rich results
4. **Phase 4** (4h) — Preview panel, big UX improvement
5. **Phase 5** (4h) — Focus keyword, the "Yoast experience"
6. **Phase 6** (2h) — FAQ schema, nice to have
7. **Phase 7** (6h) — Search Console, advanced feature

Phases 1-5 (~13h) deliver the core "rivals Yoast" experience. Phase 6-7 are nice-to-haves.

## UI Wireframes

### SEO Preview Panel

```
┌─────────────────────────────────────────┐
│ SEO Preview                             │
├─────────────────────────────────────────┤
│                                         │
│ Google Search Preview                   │
│ ┌─────────────────────────────────────┐ │
│ │ About Us · Acme Prints              │ │  ← blue title link
│ │ acmeprints.com › about              │ │  ← green URL
│ │ Learn about our story and the       │ │  ← grey description
│ │ passion behind our handmade prints. │ │
│ │ Based in London since 2020...       │ │
│ └─────────────────────────────────────┘ │
│                                         │
│ Title: 52/60 chars ●                    │  ← green dot
│ Description: 145/160 chars ●            │  ← green dot
│                                         │
│ Social Card Preview                     │
│ ┌─────────────────────────────────────┐ │
│ │ ┌─────────────────────────────────┐ │ │
│ │ │                                 │ │ │
│ │ │      [OG Image Preview]         │ │ │
│ │ │                                 │ │ │
│ │ └─────────────────────────────────┘ │ │
│ │ acmeprints.com                      │ │
│ │ About Us                            │ │
│ │ Learn about our story...            │ │
│ └─────────────────────────────────────┘ │
│                                         │
└─────────────────────────────────────────┘
```

### SEO Checklist

```
┌─────────────────────────────────────────┐
│ SEO Score: 7/9 ●●●●●●●○○ Good           │
├─────────────────────────────────────────┤
│                                         │
│ Focus keyword: [handmade prints_______] │
│                                         │
│ ✓ Keyword in title                      │
│ ✓ Keyword in meta description           │
│ ✓ Keyword in URL                        │
│ ✗ Keyword in first paragraph            │
│   → Add "handmade prints" to your       │
│     opening paragraph                   │
│ ✓ Meta description length (145 chars)   │
│ ✓ Title length (52 chars)               │
│ ✓ Image with alt text                   │
│ ✓ Internal links (3 found)              │
│ ○ External links (optional)             │
│                                         │
└─────────────────────────────────────────┘
```

### Business Info Settings

```
┌─────────────────────────────────────────┐
│ Business Information                    │
│ Used for search engine rich results     │
├─────────────────────────────────────────┤
│                                         │
│ Business type:                          │
│ ○ Online store (default)                │
│ ○ Local business (adds address)         │
│                                         │
│ Contact email: [hello@acme.com_______]  │
│ Contact phone: [+44 20 1234 5678_____]  │
│                                         │
│ ▼ Address (for local business)          │
│   Street: [123 Print Lane____________]  │
│   City: [London____________________]    │
│   Region: [England_________________]    │
│   Postal code: [SW1A 1AA___________]    │
│   Country: [United Kingdom_________]    │
│                                         │
│ Social profiles (also shown in footer): │
│ ┌───────────────────────────────────┐   │
│ │ Instagram  https://instagram...  │   │
│ │ Twitter    https://twitter.com.. │   │
│ └───────────────────────────────────┘   │
│ [+ Add profile]                         │
│                                         │
└─────────────────────────────────────────┘
```

## Open Questions

1. **Where should SEO controls live after editor reorg?**
   - Option A: Keep in Settings tab (page-level)
   - Option B: New "SEO" accordion in Page tab
   - Option C: Dedicated SEO tab (4 tabs total)

   Recommendation: Option B — SEO is page-specific, belongs with page content

2. **Should SEO score block publishing?**
   - No — it's guidance, not a gate
   - Show warning but allow publish with low score

3. **How to handle product page SEO?**
   - Products sync from providers, limited customisation
   - Allow focus keyword override?
   - Allow meta description override?

   Recommendation: Allow overrides stored in local DB, merged with synced data

4. **Search Console: require for all users?**
   - Make it optional, show benefits
   - Works without it, enhanced with it

## Dependencies

- **Editor reorganisation** — SEO controls placement depends on final tab structure
- **Social links** (from editor-reorg) — Reuse for Organization schema sameAs
- **Reviews feature** (future) — Review schema depends on this