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:

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

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

# 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