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,126 @@
+# Known Issues and Gotchas
+
+Confirmed issues, limitations, and workarounds for SmartCrawl v3.15.0.
+
+## Fixed in v3.15.0 (Verify You're Updated)
+
+These were bugs in prior versions — confirm you're on 3.15.0+:
+
+| Issue | Description |
+|-------|-------------|
+| Editor freezing | Editor got stuck when typing for >2 minutes with SmartCrawl enabled |
+| Focus keywords with numbers | SmartCrawl failed to detect focus keywords containing numbers |
+| Large content pages | SEO checks failed on very large content pages |
+| Social accounts erased | Social accounts wiped from Schema General Settings on save |
+| Taxonomy archives | Categories/tags not saving under Taxonomy Archives settings |
+| Blog/Posts archive | Global Titles & Meta didn't apply to blog archive when static front page was set |
+
+## Current Known Issues
+
+### Redirect Ordering
+
+**Issue:** Redirects cannot be reordered once added.
+
+**Workaround:** Delete the redirect and recreate it. For complex redirect lists, consider exporting as JSON, editing the order, and re-importing.
+
+### Regex Redirects Inconsistency
+
+**Issue:** Some users report regex patterns not working in SmartCrawl despite being valid on regex101.com.
+
+**Workaround:** Use simpler patterns. Test thoroughly after creating. For complex regex redirects, consider handling them at the server level (`.htaccess` or Nginx config).
+
+### Sitemap 1,000 Post Limit
+
+**Issue:** Sitemaps are limited to 1,000 most recent posts per post type to prevent memory errors.
+
+**Impact:** Older posts on large sites may not appear in the sitemap.
+
+**Workaround:** For sites with 1,000+ posts, consider supplementing with a manual sitemap or contacting WPMU DEV support.
+
+### Noindex + Sitemap Disconnect
+
+**Issue:** Setting a page to `noindex` does NOT automatically exclude it from the sitemap.
+
+**Workaround:** Manually exclude noindexed pages from the sitemap by post ID. **Always do both when noindexing a page.**
+
+### No IndexNow Support
+
+**Issue:** SmartCrawl does not support the IndexNow protocol (unlike Yoast and Rank Math).
+
+**Impact:** Bing and Yandex won't get instant notification of content changes. Google does not support IndexNow anyway (they use their own crawl notification).
+
+**Workaround:** Not critical — SmartCrawl's "Instant Indexing" feature notifies Google directly.
+
+### Auto-Linking + WooCommerce Conflict (Pro)
+
+**Issue:** Auto-linking can cause issues with WooCommerce cart and account page caching.
+
+**Workaround:** Exclude WooCommerce cart, checkout, and account pages from auto-linking in the settings.
+
+### WPML Duplicate Sitemap URLs
+
+**Issue:** When using WPML (multilingual plugin), duplicate homepage URLs appear in the sitemap.
+
+**Workaround:** Manually exclude duplicate URLs from the sitemap.
+
+### OpenGraph Persistence After Disabling
+
+**Issue:** OG tags can remain active on the homepage even after deactivating Open Graph in the setup wizard.
+
+**Workaround:** Manually disable OG for the homepage in SmartCrawl > Social settings, or clear any cached pages.
+
+### Auto-Linking Tab in Free Version
+
+**Issue:** The auto-linking tab appears in the free version UI but the feature does not function without Pro.
+
+**Impact:** Cosmetic only — confusing but not harmful.
+
+### Plugin Update Data Loss (Rare)
+
+**Issue:** At least one user reported keywords, descriptions, and titles being wiped on plugin update.
+
+**Workaround:** Always export SmartCrawl settings (JSON backup) before updating the plugin. This is a rare issue but catastrophic when it happens.
+
+## Plugin Conflicts
+
+### Google Web Stories
+
+**Issue:** SmartCrawl conflicts with the Google Web Stories editor.
+
+**Workaround:** Exclude Web Stories post type from SmartCrawl processing, or use a different SEO plugin for Web Stories.
+
+### Other SEO Plugins
+
+**Issue:** Running multiple SEO plugins simultaneously causes duplicate meta tags, conflicting sitemaps, and schema errors.
+
+**Fix:** Only run one SEO plugin at a time. Use SmartCrawl's import tool when migrating from another plugin.
+
+### Caching Plugins
+
+**Issue:** Page caching can serve stale meta tags after SmartCrawl changes.
+
+**Fix:** Clear the cache after making SEO changes. On your server with EA-Nginx:
+```bash
+rm -rf /var/cache/ea-nginx/proxy/<account>/*
+```
+
+### WP Hummingbird
+
+SmartCrawl and Hummingbird (both WPMU DEV) generally work well together. No known conflicts.
+
+## Best Practices to Avoid Issues
+
+1. **Export settings before every plugin update** — JSON backup takes 10 seconds
+2. **Keep SmartCrawl updated** — many issues are fixed in recent versions
+3. **Never run two SEO plugins** — deactivate the old one after importing
+4. **Manually sync noindex and sitemap exclusions** — SmartCrawl doesn't auto-sync these
+5. **Test redirects after creating** — especially regex patterns
+6. **Clear cache after SEO changes** — especially on sites with server-level caching
+7. **Be patient with Google** — title/description changes can take up to a week to reflect in SERPs
+8. **Use the SEO Health Checkup** periodically — catches configuration drift
+
+## Where to Get Help
+
+- [WPMU DEV Documentation](https://wpmudev.com/docs/wpmu-dev-plugins/smartcrawl/)
+- [WPMU DEV Support](https://wpmudev.com/hub/support/) (Pro members)
+- [WordPress.org Support Forum](https://wordpress.org/support/plugin/smartcrawl-seo/) (Free version)