Initial commit — SEO Guidelines & SmartCrawl reference

SmartCrawl plugin reference (11 docs): - Overview, configuration, titles & meta, schema, sitemaps, social/OG, redirects, breadcrumbs, content analysis, hooks/filters, known issues SEO strategy playbook (6 docs): - Keyword research, per-page-type selection, on-page optimization, local SEO, technical SEO, content strategy Reusable templates (3): - Site audit checklist, keyword research worksheet, page optimization checklist Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-17 13:32:17 -05:00
commit 6eff12e8ac
21 changed files with 3301 additions and 0 deletions
@@ -0,0 +1,143 @@
+# Social: Open Graph & Twitter Cards
+
+SmartCrawl controls how your pages appear when shared on social media platforms. Open Graph tags handle Facebook, Instagram, LinkedIn, and Pinterest. Twitter Card tags handle X (formerly Twitter).
+
+## Open Graph (OG) Tags
+
+### What They Control
+
+When someone shares a link on Facebook, Instagram, LinkedIn, or Pinterest, the platform reads these tags to determine:
+
+- **Title** — The headline shown in the share card
+- **Description** — The preview text
+- **Image** — The thumbnail/preview image
+- **URL** — The canonical URL
+- **Type** — Content type (website, article, product, etc.)
+
+### Global Settings
+
+| Setting | Recommendation |
+|---------|---------------|
+| Enable Open Graph | Yes (all post types) |
+| Default OG Image | Set a branded fallback image (**1200x630px**) |
+| Site Name | Your business name |
+
+### Per-Post Type Defaults
+
+Configure in SmartCrawl > Social for each post type:
+
+- **Posts:** OG type = `article`, use post title and excerpt
+- **Pages:** OG type = `website`, use page title and excerpt
+- **Products:** Enable WooCommerce Product OG toggle (adds `og:type=product`, price, availability automatically)
+
+### Per-Post Overrides
+
+For important pages, set custom OG values in the SmartCrawl meta box:
+
+| Field | Guidance |
+|-------|----------|
+| OG Title | Can differ from SEO title — make it more engaging/clickable for social |
+| OG Description | Can be longer than meta description (up to ~300 characters). Write for social context. |
+| OG Image | Must be **1200x630px** for optimal rendering. Avoid text-heavy images (Facebook may reject them). |
+
+### Key OG Tags Output
+
+```html
+<meta property="og:title" content="Page Title" />
+<meta property="og:description" content="Page description for social sharing" />
+<meta property="og:image" content="https://example.com/image-1200x630.jpg" />
+<meta property="og:url" content="https://example.com/page/" />
+<meta property="og:type" content="article" />
+<meta property="og:site_name" content="Site Name" />
+```
+
+## Twitter Cards
+
+### Card Types
+
+SmartCrawl supports:
+
+| Type | Appearance |
+|------|-----------|
+| `summary` | Small square thumbnail + title + description |
+| `summary_large_image` | Large image above title + description |
+
+**Recommendation:** Use `summary_large_image` for most content — larger images get more engagement.
+
+### Configuration
+
+| Setting | Recommendation |
+|---------|---------------|
+| Enable Twitter Cards | Yes |
+| Default Card Type | `summary_large_image` |
+| Twitter Site Handle | `@yourbrand` (your brand's Twitter handle) |
+
+### Per-Post Overrides
+
+Twitter Card title, description, and image can be set separately from OG tags. This allows platform-specific messaging:
+
+- **Twitter title:** Shorter, punchier (Twitter is fast-scrolling)
+- **Twitter image:** Same 1200x630px works, but can use a different image optimized for Twitter's crop
+
+## Pinterest Verification
+
+Add your Pinterest verification meta tag in SmartCrawl > Social > Pinterest:
+
+```html
+<meta name="p:domain_verify" content="your-verification-code" />
+```
+
+This verifies your website with Pinterest and enables rich pins.
+
+## Image Guidelines
+
+### Optimal Dimensions
+
+| Platform | Recommended Size | Minimum |
+|----------|-----------------|---------|
+| Facebook | 1200x630px | 600x315px |
+| Twitter | 1200x630px | 300x157px |
+| LinkedIn | 1200x627px | 1200x627px |
+| Pinterest | 1000x1500px (2:3 ratio) | 600x900px |
+
+### Image Best Practices
+
+- Use **1200x630px** as the universal default (works well on all platforms)
+- Avoid images with more than 20% text overlay (Facebook may throttle reach)
+- Use high-contrast images that are recognizable at small sizes
+- Set a **default/fallback OG image** in SmartCrawl's global settings for pages without featured images
+- Product pages should use the product image as OG image
+
+## Debugging Social Shares
+
+### Facebook
+
+Use the [Facebook Sharing Debugger](https://developers.facebook.com/tools/debug/):
+1. Enter your URL
+2. Click "Debug"
+3. Verify title, description, and image are correct
+4. Click "Scrape Again" to force Facebook to re-fetch after making changes
+
+### Twitter
+
+Use the [Twitter Card Validator](https://cards-dev.twitter.com/validator):
+1. Enter your URL
+2. Click "Preview card"
+3. Verify the card renders correctly
+
+### LinkedIn
+
+LinkedIn caches aggressively. Use their [Post Inspector](https://www.linkedin.com/post-inspector/):
+1. Enter your URL
+2. Review the preview
+3. Click "Refresh" to clear cache
+
+## Common Issues
+
+| Issue | Fix |
+|-------|-----|
+| Old image showing on Facebook | Use Facebook Debugger > "Scrape Again" |
+| OG tags present but not rendering | Check for duplicate OG tags from other plugins/theme |
+| No image in share preview | Set a default OG image in SmartCrawl global settings |
+| WooCommerce products missing price in share | Enable the "WooCommerce Product Open Graph" toggle |
+| OG tags still active after disabling | Known issue — may persist on homepage after wizard deactivation. Clear manually. |