diff --git a/docs/plans/seo-enhancements.md b/docs/plans/seo-enhancements.md new file mode 100644 index 0000000..409dd31 --- /dev/null +++ b/docs/plans/seo-enhancements.md @@ -0,0 +1,369 @@ +# 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 `` 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