seo/guides/SEO_ANALYZER_GUIDE.md

Multi-Site SEO Analyzer Guide

Purpose: Fetch posts from all 3 WordPress sites, analyze titles and meta descriptions, and provide AI-powered optimization recommendations.

Output: CSV with detailed analysis + Markdown summary report

---

Overview

The Multi-Site SEO Analyzer does the following:

1. Fetches all published posts from your 3 WordPress sites (mistergeek.net, webscroll.fr, hellogeek.net)
2. Analyzes each post's:
   • Title (length, power words, numbers, readability)
   • Meta description (presence, length, call-to-action)
3. Scores posts on SEO best practices (0-100)
4. Generates AI recommendations for your top priority posts
5. Exports results to CSV for action

---

Setup

Step 1: Configure WordPress Access

Update your .env file with credentials for all 3 sites:

# Primary site (fallback for others if not specified)
WORDPRESS_URL=https://www.mistergeek.net
WORDPRESS_USERNAME=your_username
WORDPRESS_APP_PASSWORD=your_app_password

# Site 1: mistergeek.net (uses primary credentials if not specified)
WORDPRESS_MISTERGEEK_URL=https://www.mistergeek.net
WORDPRESS_MISTERGEEK_USERNAME=your_username
WORDPRESS_MISTERGEEK_PASSWORD=your_app_password

# Site 2: webscroll.fr
WORDPRESS_WEBSCROLL_URL=https://www.webscroll.fr
WORDPRESS_WEBSCROLL_USERNAME=your_username
WORDPRESS_WEBSCROLL_PASSWORD=your_app_password

# Site 3: hellogeek.net
WORDPRESS_HELLOGEEK_URL=https://www.hellogeek.net
WORDPRESS_HELLOGEEK_USERNAME=your_username
WORDPRESS_HELLOGEEK_PASSWORD=your_app_password

# OpenRouter API (for AI recommendations)
OPENROUTER_API_KEY=your_key

Note: If a site's credentials are not specified, the script uses the primary site credentials.

Step 2: Verify Your .env

cat .env | grep -E "WORDPRESS|OPENROUTER"

---

Usage

Basic Usage (with AI recommendations)

python scripts/multi_site_seo_analyzer.py

This will:

• Fetch all posts from 3 sites
• Analyze each post
• Generate AI recommendations for top 10 worst-scoring posts
• Export results to CSV and Markdown

Include Draft Posts

python scripts/multi_site_seo_analyzer.py --include-drafts

Analyzes both published and draft posts. Useful for:

• Optimizing posts before publishing
• Recovering removed content saved as drafts
• Getting full picture of all content
• CSV will show status column (publish/draft)

Skip AI (Save Cost)

python scripts/multi_site_seo_analyzer.py --no-ai

Analyzes posts without AI recommendations. Good for:

• Quick overview
• Sites with >500 posts (AI costs add up)
• Budget testing

Generate AI for Top 20 Posts

python scripts/multi_site_seo_analyzer.py --top-n 20

AI recommendations for 20 worst-scoring posts instead of 10.

Combine Options

# Analyze published + drafts with AI for top 20
python scripts/multi_site_seo_analyzer.py --include-drafts --top-n 20

# Analyze drafts only (then filter in Excel to status=draft)
python scripts/multi_site_seo_analyzer.py --include-drafts --no-ai

Custom Output File

python scripts/multi_site_seo_analyzer.py --output output/custom_report.csv

---

Output Files

1. CSV Report: seo_analysis_TIMESTAMP.csv

Contains all analyzed posts with columns:

Column	Description
site	Website (mistergeek.net, webscroll.fr, hellogeek.net)
post_id	WordPress post ID
title	Post title
slug	Post slug
url	Full post URL
meta_description	Current meta description
title_score	Title SEO score (0-100)
title_issues	Title problems (too short, no power words, etc.)
title_recommendations	How to improve title
meta_score	Meta description SEO score (0-100)
meta_issues	Meta description problems
meta_recommendations	How to improve meta
overall_score	Combined score (40% title + 60% meta)
ai_recommendations	Claude-generated specific recommendations

2. Summary Report: seo_analysis_TIMESTAMP_summary.md

Human-readable markdown with:

• Overall statistics (total posts, average score, cost)
• Priority issues (missing meta, weak titles, weak descriptions)
• Per-site breakdown
• Top 5 posts to optimize on each site
• Legend explaining scores

---

Understanding Scores

Title Score (0-100)

What's analyzed:

• Length (target: 50-70 characters)
• Power words (best, complete, guide, ultimate, essential, etc.)
• Numbers (top 5, 2025, etc.)
• Special characters that might break rendering

Optimal title example: "The Complete 2025 Guide to VPN Services (Updated)"

• Length: 57 characters ✓
• Power words: "Complete", "Guide" ✓
• Numbers: "2025" ✓
• Score: 95/100

Meta Description Score (0-100)

What's analyzed:

• Presence (missing = 0 score)
• Length (target: 120-160 characters)
• Call-to-action (learn, discover, find, check, etc.)

Optimal meta example: "Discover the best VPN services for 2025. Compare 50+ options, learn about encryption, and find the perfect VPN for your needs. Updated monthly."

• Length: 149 characters ✓
• CTA: "Discover", "Compare", "learn", "find" ✓
• Score: 90/100

Overall Score (0-100)

Overall = (Title Score × 40%) + (Meta Score × 60%)

Meta description weighted heavier because it directly impacts click-through rates from search results.

---

Action Plan

1. Review Results

# Open the summary report
open output/reports/seo_analysis_*.md

# Or open the detailed CSV
open output/reports/seo_analysis_*.csv

2. Prioritize by Score

High Priority (Score < 50):

• Title issues OR missing/weak meta
• Implement AI recommendations immediately
• Estimated impact: 10-20% CTR improvement

Medium Priority (Score 50-75):

• Minor title or meta issues
• Apply recommendations when convenient
• Estimated impact: 5-10% CTR improvement

Low Priority (Score > 75):

• Already optimized
• Only update if major content changes

3. Batch Implementation

For WordPress:

1. Go to WordPress admin

2. Edit post

3. Update title (if recommended)

4. Update meta description in Yoast SEO or All in One SEO:

   • Yoast: Bottom of editor → "SEO" tab → Meta description
   • AIOSEO: Right sidebar → "General" → Description

5. Save post

OR use bulk operations if your SEO plugin supports it.

4. Monitor Impact

Re-run the analyzer in 30 days:

python scripts/multi_site_seo_analyzer.py

Track improvements:

• Average score increase
• Fewer posts with score < 50
• Posts moved from "Missing meta" to "Strong meta"

---

Cost Estimation

AI Recommendation Costs

Using Claude 3.5 Sonnet via OpenRouter ($3 input / $15 output per 1M tokens):

Scenario 1: 10 posts with AI

• ~2,500 input tokens per post × 10 = 25,000 input tokens
• ~500 output tokens per post × 10 = 5,000 output tokens
• Cost: (25,000 × $3 + 5,000 × $15) / 1,000,000 = $0.105 (~11¢)

Scenario 2: 50 posts with AI

• 125,000 input + 25,000 output tokens
• Cost: $0.525 (~52¢)

Scenario 3: No AI (--no-ai flag)

• Cost: $0.00

Monthly Scenarios

Scenario	Frequency	Cost/Month
No AI	Weekly	$0
10 posts/week	Weekly	~€0.40
20 posts/week	Weekly	~€0.80
50 posts/month	Once	~€0.50

---

Troubleshooting

"Connection refused" on a site

Problem: WordPress site is down or credentials are wrong.

Solutions:

1. Check site URL is correct (https, www vs no-www)
2. Verify credentials: Try logging in manually
3. Check if site has REST API enabled: https://yoursite.com/wp-json/
4. Skip that site temporarily (remove from config, re-run)

"No posts found"

Problem: API returns 0 posts.

Solutions:

1. Verify credentials have permission to read posts
2. Check if posts exist on the site
3. Try without authentication (remove from config)
4. Check if REST API is disabled

AI recommendations are empty

Problem: OpenRouter API call failed.

Solutions:

1. Verify OPENROUTER_API_KEY is set: echo $OPENROUTER_API_KEY
2. Check API key is valid (not expired, has credits)
3. Try with --no-ai flag to verify the rest works
4. Check internet connection

Memory issues with 1000+ posts

Problem: Script runs out of memory.

Solutions:

1. Run --no-ai version first (lighter)
2. Analyze one site at a time (modify config temporarily)
3. Increase system memory or close other apps

---

Advanced Usage

Analyze One Site

Temporarily comment out sites in config.py or create a custom script:

from scripts.multi_site_seo_analyzer import MultiSiteSEOAnalyzer
from scripts.config import Config

analyzer = MultiSiteSEOAnalyzer()

# Override to just one site
analyzer.sites_config = {
    'mistergeek.net': Config.WORDPRESS_SITES['mistergeek.net']
}

analyzer.run(use_ai=True, top_n=20)

Export to Google Sheets

1. Download the CSV
2. Open Google Sheets
3. File → Import → Upload CSV
4. Share link with team
5. Filter by site or score
6. Add "Completed" checkbox column
7. Track progress as you optimize

Integrate with WordPress via Zapier

1. Export CSV from analyzer
2. Use Zapier to trigger WordPress post updates
3. Automatically update meta descriptions for high-priority posts
4. (Advanced - requires Zapier Pro)

---

Examples

Example 1: Post with Low Title Score

Title: "VPN"
Title Issues: Too short (3), Missing power word, No number
Title Score: 10/100

Recommendation: Expand title to include benefit and year
Better Title: "Best VPN Services 2025: Complete Guide"

Example 2: Post with Missing Meta

Meta Description: [MISSING]
Meta Score: 0/100

AI Recommendation:
"Write a meta description: 'Learn about the best VPN services for 2025.
Compare 50+ providers, understand encryption, and choose the right VPN
for your needs. Updated weekly.' (150 characters)"

Example 3: Strong Post (No Changes Needed)

Title: "The Complete Guide to NordVPN: Features, Pricing, and Reviews"
Title Issues: None
Title Score: 95/100

Meta: "Comprehensive review of NordVPN including speed tests, security features, pricing plans, and user reviews. Find out if NordVPN is right for you."
Meta Issues: None
Meta Score: 95/100

Overall Score: 95/100
Status: No changes needed ✓

---

FAQ

Q: How often should I run this? A: Monthly or after publishing 10+ new posts. More frequent for highly competitive topics.

Q: Will changing titles affect SEO? A: No, titles can be improved without penalty. The URL stays the same, so search rankings are preserved.

Q: Should I update all weak meta descriptions? A: Prioritize posts with traffic. Update high-traffic posts first for maximum impact.

Q: Can I use this on a site with 5000+ posts? A: Yes, but consider:

• Using --no-ai on first run (faster)
• Running once per month instead of weekly
• Focusing AI analysis on high-traffic posts only

Q: What if my site uses a different SEO plugin? A: The script looks for common meta description fields. If it finds nothing, add one manually. Plugin doesn't matter; the meta description HTML is standard.

---

Next Steps

1. Run the analyzer: python scripts/multi_site_seo_analyzer.py
2. Review the report: Open output/reports/seo_analysis_*_summary.md
3. Prioritize: Identify posts with score < 50
4. Implement: Update titles and meta descriptions
5. Track: Re-run in 30 days to measure improvement
6. Monitor: Watch Google Search Console for CTR improvements

Ready to optimize? Let's go! 🚀