craig/SEO-Guidelines-Smartcrawl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit — SEO Guidelines & SmartCrawl reference

Browse Source 
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>
This commit is contained in:
craig
2026-04-17 13:32:17 -05:00
commit 6eff12e8ac
21 changed files with 3301 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
smartcrawl/breadcrumbs.md
+146
View File
@@ -0,0 +1,146 @@
# Breadcrumbs
SmartCrawl provides breadcrumb navigation with built-in Schema.org `BreadcrumbList` markup. Breadcrumbs improve both UX (users can navigate up the site hierarchy) and SEO (Google displays breadcrumb trails in search results).
## Enabling Breadcrumbs
1. Go to **SmartCrawl > Advanced Tools > Breadcrumbs**
2. Toggle the module ON
3. Configure separator and display options
4. Add the breadcrumb output to your theme
## Adding Breadcrumbs to Your Theme
### Method 1: Shortcode
```
[smartcrawl_breadcrumbs]
```
Place this in any post, page, widget, or theme template.
### Method 2: Shortcode with Custom Wrapper
```
[smartcrawl_breadcrumbs before="<nav aria-label='Breadcrumb'>" after="</nav>"]
```
The `before` and `after` parameters wrap the breadcrumb trail with custom HTML.
### Method 3: PHP (Theme Template)
```php
<?php
if ( function_exists( 'smartcrawl_breadcrumbs' ) ) {
smartcrawl_breadcrumbs();
}
?>
```
Place this in your theme's `header.php`, `single.php`, `page.php`, or a custom template part.
## Configuration
### Separator
Choose from presets or enter custom HTML:
| Preset | Output |
|--------|--------|
| `>` | Home > Category > Page |
| `/` | Home / Category / Page |
| `»` | Home » Category » Page |
| Custom | Any HTML character or element |
**Recommendation:** Use `>` or `»` — they visually indicate hierarchy.
### Display Options
| Option | Description |
|--------|-------------|
| Show on homepage | Whether breadcrumbs appear on the homepage (usually no — it would just show "Home") |
| Home link text | Default "Home" — can be customized (e.g., site name) |
| Post breadcrumb type | Show category hierarchy or just parent page |
## Schema Output
SmartCrawl automatically outputs `BreadcrumbList` schema markup alongside the visible breadcrumbs:
```json
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://example.com/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Services",
"item": "https://example.com/services/"
},
{
"@type": "ListItem",
"position": 3,
"name": "Basic Rider Course"
}
]
}
```
This produces breadcrumb navigation in Google search results:
```
example.com > Services > Basic Rider Course
```
## Styling
SmartCrawl outputs breadcrumbs with CSS classes you can target:
```css
/* Breadcrumb container */
.smartcrawl-breadcrumbs {
font-size: 14px;
padding: 10px 0;
color: #666;
}
/* Individual breadcrumb links */
.smartcrawl-breadcrumbs a {
color: #0066cc;
text-decoration: none;
}
.smartcrawl-breadcrumbs a:hover {
text-decoration: underline;
}
/* Separator */
.smartcrawl-breadcrumbs .separator {
margin: 0 8px;
color: #999;
}
/* Current page (last item, no link) */
.smartcrawl-breadcrumbs .current {
color: #333;
font-weight: 500;
}
```
## White Label Support
SmartCrawl Pro supports white labeling the breadcrumb module — you can remove WPMU DEV branding from the output.
## Best Practices
1. **Place breadcrumbs near the top of the page** — above the main content, below the header
2. **Don't show on homepage** — it adds no value (just "Home")
3. **Keep the trail short** — Home > Category > Page is ideal. Avoid deep nesting.
4. **Validate the schema** at [Google Rich Results Test](https://search.google.com/test/rich-results)
5. **Ensure the hierarchy makes sense** — breadcrumbs should reflect the actual site structure
smartcrawl/configuration.md
+230
View File
@@ -0,0 +1,230 @@
# SmartCrawl Configuration Guide
Module-by-module setup with recommended settings for production WordPress sites.
## Initial Setup
### 1. Install and Activate
Install SmartCrawl from the WordPress plugin repository or upload the WPMU DEV Pro version. On activation, the Setup Wizard launches.
### 2. Setup Wizard
The wizard enables all modules by default. Recommended approach:
- **Run the wizard** — accept all defaults
- **Then configure each module** per the sections below
- **If migrating from another SEO plugin** (Yoast, Rank Math, AIOSEO): use the Import tool in Settings to pull in existing titles, descriptions, and meta data before making changes
### 3. Conflict Check
SmartCrawl detects other SEO plugins. **Never run two SEO plugins simultaneously** — they will output duplicate meta tags. Deactivate the old plugin after importing its data.
---
## Module: Titles & Meta
See [titles-and-meta.md](titles-and-meta.md) for the full macro reference.
### Recommended Global Settings
**Homepage:**
```
Title: %%sitename%% %%sep%% [Primary service/value proposition]
Description: Hand-write this — 150-160 characters, include primary keyword + CTA
```
**Posts:**
```
Title: %%title%% %%sep%% %%sitename%%
Description: %%excerpt%% (override per-post for important pages)
```
**Pages:**
```
Title: %%title%% %%sep%% %%sitename%%
Description: Leave blank at template level — hand-write per page
```
**Categories/Tags:**
```
Title: %%term_title%% %%sep%% %%sitename%%
Description: %%term_description%%
```
**Separator:** Use `|` or `—` (clean, modern look in SERPs)
### Key Settings
- **Noindex tag archives** unless your tags have substantial unique content
- **Noindex author archives** on single-author sites (duplicate of your posts page)
- **Noindex paginated archives** (`/page/2/`, `/page/3/`) — thin content
- **Check custom post types** — WooCommerce products, portfolio items, etc. must be explicitly enabled
---
## Module: Social (Open Graph & Twitter)
### Global Settings
| Setting | Recommendation |
|---------|---------------|
| Default OG Image | Set a branded fallback image (1200x630px) |
| Facebook OG | Enable for all post types |
| Twitter Cards | Enable — use `summary_large_image` card type |
| Pinterest Verification | Add your Pinterest meta tag if applicable |
### Per-Post Type Settings
- **Posts/Pages:** Enable OG and Twitter, use post title and excerpt as defaults
- **Products (WooCommerce):** Enable the "WooCommerce Product Open Graph" toggle — auto-adds `og:type=product`, price, availability
- **Custom post types:** Enable and verify OG tags render correctly
### Per-Post Overrides
For important pages, always set custom OG title, description, and image:
- OG title can differ from the SEO title (e.g., more engaging/clickable for social)
- OG image should be exactly **1200x630px** for best rendering across platforms
- OG description can be longer than meta description (up to ~300 characters)
---
## Module: Sitemap
### Recommended Settings
| Setting | Value |
|---------|-------|
| XML Sitemap | Enable |
| Include post types | Posts, Pages, Products, and any public custom post types |
| Include taxonomies | Categories (yes), Tags (only if indexable), custom taxonomies |
| Image Sitemap | Enable — helps with Google Images indexing |
| Google News Sitemap | Enable only if the site publishes news-style content |
| Notify search engines | Automatic mode |
### Exclusions
Exclude from sitemap:
- Thank you / confirmation pages
- Internal-use pages (login, dashboard, etc.)
- Any page set to `noindex` — **SmartCrawl does not do this automatically**
- Thin content pages with little SEO value
### Important Notes
- Sitemap is limited to **1,000 most recent posts** to prevent memory errors
- After making sitemap changes, use the **"New Crawl" button** to notify Google
- Verify your sitemap loads at `yoursite.com/sitemap.xml`
- Submit the sitemap URL in Google Search Console
---
## Module: Schema / Structured Data
See [schema-markup.md](schema-markup.md) for the full type reference.
### Recommended Setup
1. **Organization Schema** — Enable globally with:
- Business name, logo, contact info
- Social media profile URLs
- Same-as links to directory listings
2. **LocalBusiness Schema** — For local businesses, add with:
- Full NAP (name, address, phone)
- Opening hours
- Geo coordinates
- Area served
- Appropriate subtype (60+ available)
3. **Article/WebPage Schema** — Default for posts and pages respectively
4. **Per-page schema** — Add specific types where applicable:
- **FAQ** on pages with Q&A content
- **Event** on event listing pages
- **Course** on educational offerings
- **Product** on WooCommerce products (auto-handled)
5. **Validate schema** at [Google Rich Results Test](https://search.google.com/test/rich-results) after deploying
---
## Module: Redirects
See [redirects.md](redirects.md) for the full reference.
### Quick Setup
- Enable the Redirects module
- Set default redirect type to **301 (Permanent)**
- Enable **"Auto-redirect deleted posts"** (v3.9.0+) to catch deleted content
- Import any existing redirects from `.htaccess` or a previous plugin
---
## Module: Content Analysis
See [content-analysis.md](content-analysis.md) for scoring details.
### Recommended Approach
- **Always set a focus keyword** for every published page/post
- Use **up to 3 keywords** per page (1 primary + 2 secondary)
- Aim for **all green checks** on the SEO analysis tab
- Target a **Flesch-Kincaid readability score of 60-70** (8th-grade level)
- Don't chase a perfect score at the expense of natural writing
---
## Module: Breadcrumbs
See [breadcrumbs.md](breadcrumbs.md) for implementation details.
### Quick Setup
1. Enable Breadcrumbs in the Advanced Tools module
2. Add `[smartcrawl_breadcrumbs]` shortcode to your theme template or use the PHP function
3. Choose a separator (` > ` or ` / ` are most common)
4. Verify the breadcrumb trail renders correctly and the schema output validates
---
## Module: Robots.txt (Pro Only)
### Recommended Content
```
User-agent: *
Allow: /
Disallow: /wp-admin/
Allow: /wp-admin/admin-ajax.php
Sitemap: https://yoursite.com/sitemap.xml
```
**Important:** Use full absolute URLs for sitemap directives.
**Do not block CSS/JS files** — Google needs them to render pages for mobile-first indexing.
---
## Settings: Import/Export
- **Export** your SmartCrawl configuration as JSON after setting up a site
- **Import** that configuration when setting up similar sites to save time
- Settings are transferable between sites but **titles/descriptions are templates, not content** — they'll adapt to each site's content via macros
---
## Post-Setup Checklist
After configuring SmartCrawl:
- [ ] Run the **SEO Health Checkup** and address all red/yellow items
- [ ] Verify `sitemap.xml` loads and is submitted in Google Search Console
- [ ] Check 5-10 key pages for correct title tags and meta descriptions (view source)
- [ ] Verify Open Graph tags render correctly (use [Facebook Sharing Debugger](https://developers.facebook.com/tools/debug/))
- [ ] Validate schema markup with [Google Rich Results Test](https://search.google.com/test/rich-results)
- [ ] Check robots.txt at `yoursite.com/robots.txt`
- [ ] Confirm no duplicate SEO plugins are active
- [ ] Set focus keywords on all priority pages
smartcrawl/content-analysis.md
+169
View File
@@ -0,0 +1,169 @@
# Content Analysis
SmartCrawl provides real-time SEO and readability analysis in both the Classic Editor and Block Editor. This module is the primary tool for optimizing individual posts and pages.
## Focus Keywords
### How They Work
- Set **up to 3 focus keywords** per post/page (1 primary + 2 secondary)
- Enter as comma-separated values in the SmartCrawl meta box
- SmartCrawl checks the page content against each keyword
- The primary keyword gets the most checks; secondary keywords supplement
### Best Practices for Focus Keywords
| Rule | Details |
|------|---------|
| One primary keyword per page | The single most important search term this page should rank for |
| 1-2 secondary keywords | Closely related terms or long-tail variations |
| Match search intent | The keyword should match what the page actually delivers |
| Check for cannibalization | SmartCrawl shows the 10 most recent posts using the same keyphrase — avoid duplicates |
| Use natural language | "motorcycle safety course Anchorage" not "motorcycle+safety+course+anchorage" |
### Keyword Selection Per Page Type
| Page Type | Primary Keyword Pattern | Example |
|-----------|------------------------|---------|
| Homepage | Core service + location | "motorcycle safety courses Alaska" |
| Service page | Specific service + location | "basic rider course Anchorage" |
| Blog post | Informational long-tail | "what to wear to a motorcycle safety course" |
| Portfolio | Role + qualifier | "instructional design portfolio" |
| Contact | Brand + contact | "contact Alaska Safe Riders" |
| Landing page | Transactional long-tail | "register motorcycle course Anchorage May 2026" |
## SEO Analysis Checks
SmartCrawl runs these checks against your focus keyword(s):
### Title Tag
| Check | Pass Criteria |
|-------|---------------|
| Keyphrase in title | Primary keyphrase appears in the title tag |
| Title length | Between 50-60 characters |
| Title uniqueness | Not used by other posts |
### URL / Slug
| Check | Pass Criteria |
|-------|---------------|
| Keyphrase in URL | Primary keyphrase appears in the URL slug |
| URL structure | Uses hyphens (not underscores), reasonable length |
### Meta Description
| Check | Pass Criteria |
|-------|---------------|
| Keyphrase in description | Primary keyphrase appears in the meta description |
| Description length | 120-160 characters |
| Hand-crafted | Not auto-generated from content excerpt |
### Content
| Check | Pass Criteria |
|-------|---------------|
| Keyphrase in H1 | Primary keyphrase in the main heading |
| Keyphrase in subheadings | At least one H2/H3 contains the keyphrase |
| Keyphrase density | Appears a reasonable number of times (not too few, not stuffed) |
| Keyphrase in first paragraph | Appears within the first 100-200 words |
| Keyphrase in image alt text | At least one image has the keyphrase in its alt attribute |
| Content length | Sufficient content for the topic (no specific minimum enforced) |
### Links
| Check | Pass Criteria |
|-------|---------------|
| External links | At least one dofollow external link to a relevant, authoritative source |
| Internal links | Links to other pages on the site |
### Images
| Check | Pass Criteria |
|-------|---------------|
| Image optimization | Images have alt text, reasonable file names |
| Keyphrase in alt | At least one image alt includes the focus keyphrase |
## SEO Analysis Color Coding
| Color | Meaning |
|-------|---------|
| Green | Check passed — well optimized |
| Yellow/Gray | Needs improvement — suggestion provided |
| Red | Critical issue — should be fixed |
### Interpreting Results
- **Aim for all green** on important pages
- **Yellow is acceptable** when the suggestion would make content unnatural
- **Red should always be addressed** unless you have a specific reason to deviate
- **Don't sacrifice readability for a green check** — natural writing always wins
## Readability Analysis
SmartCrawl uses the **Flesch-Kincaid readability test** along with structural checks.
### Flesch-Kincaid Score
| Score | Reading Level | Assessment |
|-------|---------------|-----------|
| 90-100 | 5th grade | Very easy to read |
| 80-89 | 6th grade | Easy to read |
| 70-79 | 7th grade | Fairly easy |
| **60-69** | **8th-9th grade** | **Target range** |
| 50-59 | 10th-12th grade | Fairly difficult |
| 30-49 | College level | Difficult |
| 0-29 | Graduate level | Very difficult |
**Target: 60-70** (8th-grade level). This is readable by the widest audience while still sounding professional.
### Readability Checks
| Check | Standard |
|-------|----------|
| Sentence length | Average under 20 words. 14+ words = hard. 25+ words = very hard. |
| Passive voice | Minimize passive constructions (aim for <10% of sentences) |
| Paragraph length | 2-4 sentences per paragraph |
| Subheading distribution | Use subheadings every 200-300 words |
| Transition words | Use transition words to connect ideas |
### Readability Tips
- **Break up long sentences** — if a sentence has a comma and "and", it can usually be split
- **Use active voice** — "We teach motorcycle safety" not "Motorcycle safety is taught by us"
- **Short paragraphs** — walls of text hurt both readability scores and user engagement
- **Use lists and tables** where appropriate — they are easier to scan than prose
- **Write at 8th-grade level** — this is not "dumbing down," it is clear communication
> **Note:** SmartCrawl's readability analysis is reportedly "more difficult to please" than other plugins. A yellow readability score is acceptable if the content reads naturally.
## Content Analysis in the Editor
### Where to Find It
- **Classic Editor:** SmartCrawl meta box below the editor
- **Block Editor:** SmartCrawl panel in the right sidebar
### Real-Time Updates
Analysis updates as you type (with a short delay). No need to save/publish to see results.
### Keyword Cannibalization Check
When you enter a focus keyword, SmartCrawl checks your other posts and shows the **10 most recent posts using the same keyphrase**. If duplicates are found:
- Consider whether both pages are needed
- Differentiate their focus (e.g., one informational, one transactional)
- If truly duplicated, merge content into one page and redirect the other
## Workflow Recommendation
For every page you publish or optimize:
1. **Set the focus keyword(s)** before writing or after outlining
2. **Write naturally first** — don't write "for the SEO checker"
3. **Run the analysis** after drafting
4. **Address red items** — these are genuine issues
5. **Review yellow items** — fix what makes sense, skip what would make content unnatural
6. **Check readability** — simplify where possible without losing substance
7. **Preview the Google snippet** — verify title and description look good in the preview
smartcrawl/hooks-and-filters.md
+156
View File
@@ -0,0 +1,156 @@
# Hooks and Filters (Developer API)
SmartCrawl exposes **99 documented hooks** for developers, using the `wds_` prefix. These allow programmatic control over SmartCrawl's output without modifying the plugin directly.
The complete hooks documentation is maintained in the [WPMU DEV hooks-documentation repository](https://github.com/wpmudev/hooks-documentation) in the `smartcrawl-seo-hooks-doc.html` file.
## Key Filters
### Title and Meta
```php
// Filter the SEO title output
add_filter( 'wds_title', function( $title ) {
// Modify the title tag output
return $title;
});
// Filter the meta description output
add_filter( 'wds_metadesc', function( $description ) {
// Modify the meta description
return $description;
});
```
### Open Graph
```php
// Customize Open Graph title
add_filter( 'wds_custom_og_title', function( $title ) {
return $title;
});
// Customize Open Graph description
add_filter( 'wds_custom_og_description', function( $description ) {
return $description;
});
// Customize Open Graph image(s)
add_filter( 'wds_custom_og_image', function( $images ) {
// $images is an array of image URLs
return $images;
});
```
### Defaults and Options
```php
// Filter SmartCrawl default options
add_filter( 'wds_defaults', function( $defaults ) {
// Modify default option values
return $defaults;
});
```
### Admin UI
```php
// Control admin bar visibility
add_filter( 'wds-admin-ui-show_bar', function( $show ) {
// Return false to hide the SmartCrawl admin bar item
return $show;
});
```
### Sitemap
```php
// Exclude specific taxonomy terms from sitemaps
add_filter( 'wds_terms_sitemap_include_term_ids', function( $term_ids, $taxonomy ) {
// Remove specific term IDs
$exclude = array( 15, 23, 42 );
return array_diff( $term_ids, $exclude );
}, 10, 2 );
// Add extra images to sitemap entries
add_filter( 'wds_sitemap_extra_images', function( $images, $post_id ) {
// Add additional image URLs for a post
return $images;
}, 10, 2 );
```
## Key Actions
```php
// Fires after SmartCrawl saves post meta data
// Useful for syncing SEO data with external systems
add_action( 'wds_saved_postdata', function( $post_id ) {
// Handle post meta save cleanup
// SmartCrawl uses this internally to handle unchecked checkbox cleanup
});
```
## Common Use Cases
### Force a Specific Title on a Page
```php
add_filter( 'wds_title', function( $title ) {
if ( is_page( 'special-landing-page' ) ) {
return 'Custom Landing Page Title | Brand Name';
}
return $title;
});
```
### Add Custom OG Image for a Post Type
```php
add_filter( 'wds_custom_og_image', function( $images ) {
if ( is_singular( 'product' ) ) {
$custom_image = get_field( 'social_share_image' ); // ACF field
if ( $custom_image ) {
return array( $custom_image );
}
}
return $images;
});
```
### Hide SmartCrawl Admin Bar for Non-Admins
```php
add_filter( 'wds-admin-ui-show_bar', function( $show ) {
if ( ! current_user_can( 'manage_options' ) ) {
return false;
}
return $show;
});
```
### Exclude a Specific Category from Sitemap
```php
add_filter( 'wds_terms_sitemap_include_term_ids', function( $term_ids, $taxonomy ) {
if ( $taxonomy === 'category' ) {
$exclude = array( get_cat_ID( 'Uncategorized' ) );
return array_diff( $term_ids, $exclude );
}
return $term_ids;
}, 10, 2 );
```
## Hook Naming Convention
All SmartCrawl hooks follow these patterns:
- **Filters:** `wds_{feature}` — e.g., `wds_title`, `wds_metadesc`
- **Actions:** `wds_{event}` — e.g., `wds_saved_postdata`
- **UI filters:** `wds-{area}-{feature}` — e.g., `wds-admin-ui-show_bar`
## Notes
- The `wds_` prefix stands for "WPMU DEV SmartCrawl" (originally "WPMU DEV SEO")
- 96 of the 99 hooks were undocumented as of the last GitHub update — the three listed above are the most commonly used
- For the full list, inspect the plugin source code or check the hooks documentation repository
- Hook availability may vary between SmartCrawl Free and Pro versions
smartcrawl/known-issues.md
+126
View File
@@ -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)
smartcrawl/overview.md
+101
View File
@@ -0,0 +1,101 @@
# SmartCrawl Overview
SmartCrawl is a WordPress SEO plugin by WPMU DEV. Current version: **3.15.0** (January 26, 2026). Available as a free plugin on WordPress.org and a Pro version through WPMU DEV membership. Supports WordPress Multisite and has been translated into 16 locales.
## Full Feature Inventory
### Core Modules
| Module | Description |
|--------|-------------|
| **Dashboard** | One-click Setup Wizard, SEO Health score, import/export settings (JSON) |
| **SEO Health / Checkup** | Full site SEO scan with color-coded grading and recommendations |
| **Titles & Meta** | Global templates with macros + per-post overrides, Google preview snippet |
| **Social** | Open Graph (Facebook, Instagram, LinkedIn, Pinterest) + Twitter/X Cards |
| **Sitemap Generator** | XML, Google News, and Image sitemaps with configurable inclusions/exclusions |
| **Schema / Structured Data** | 20+ pre-built types + custom schema builder |
| **Content Analysis** | In-editor SEO analysis + readability scoring, up to 3 focus keywords |
### Advanced Tools (Sub-modules)
| Sub-module | Description |
|------------|-------------|
| **Redirects** | 301/302/307 redirects, regex support, bulk import/export |
| **Automatic Linking** | Auto-convert keywords to links (Pro only) |
| **Breadcrumbs** | Shortcode-based breadcrumb navigation with schema markup |
| **Moz Integration** | Domain authority and link metrics in the WP dashboard |
| **Robots.txt Editor** | Edit robots.txt from the admin (Pro only) |
| **Meta Robots** | Per-post index/noindex, follow/nofollow controls |
### Additional Features
| Feature | Description |
|---------|-------------|
| **WooCommerce SEO** | Product schema, OG tags, category SEO settings |
| **Instant Indexing** | Notifies Google when content is added/updated (not IndexNow) |
| **Import/Export** | JSON-based settings transfer between sites |
| **Role-based Access** | Control which user roles can access SEO settings |
## Free vs Pro
### Free Version Includes
- One-click setup wizard
- Titles & Meta descriptions (global templates + per-post overrides)
- XML Sitemap generator (with exclusions)
- Google News Sitemap
- Image Sitemap
- Open Graph & Twitter Cards
- SEO content analysis & readability checks (up to 3 focus keywords)
- Schema markup (all pre-built types + custom schema builder)
- 301/302/307 Redirects (basic)
- Breadcrumbs with schema
- Moz integration
- Meta robots (index/noindex, follow/nofollow)
- Multisite support
- Import/Export settings
- WooCommerce SEO
### Pro Adds
| Feature | Details |
|---------|---------|
| Scheduled SEO Audits | Automated URL crawls with email reports |
| Automatic Linking | Keyword-to-link automation across all content |
| Location-based Redirects | Geolocation rules for redirect targeting |
| Site Crawler | Broken URL detection, 404 monitoring, redirect chain detection |
| Robots.txt Editor | Edit robots.txt from the admin panel |
| White Label | Custom branding (remove WPMU DEV references) |
| MaxMind DB | Geolocation integration for location-based features |
| Priority Support | 24/7 live chat with WPMU DEV team |
### Pricing
Pro requires WPMU DEV membership (~$7.50/month), which includes all WPMU DEV premium plugins (Hummingbird, Smush, Defender, Forminator, etc.).
## Comparison: SmartCrawl vs Yoast vs Rank Math
| Feature | SmartCrawl Free | Yoast Free | Rank Math Free |
|---------|----------------|------------|----------------|
| Focus keywords per post | 3 | 1 | 5 |
| Schema types | Many + custom builder | Basic | 18+ pre-defined |
| Redirects | Yes (301/302/307) | No (Pro only) | Yes + 404 monitor |
| Breadcrumbs | Yes | Yes | Yes |
| XML Sitemap | Yes | Yes | Yes |
| News Sitemap | Yes | No (Pro) | Pro only |
| Image Sitemap | Yes | Included in main | Included in main |
| Open Graph / Twitter | Yes | Yes | Yes |
| Readability analysis | Yes (Flesch-Kincaid) | Yes (more detailed) | Yes |
| Google Search Console | No | No (limited) | Yes (built-in) |
| Google Analytics | No | No | Yes (GA4) |
| IndexNow | No | Yes | Yes |
| Auto-linking | Pro only | No | Pro only |
| WooCommerce SEO | Yes | Yes (Pro) | Yes |
| White label | Pro only | No | Pro only |
| Moz integration | Yes | No | No |
### Positioning Summary
- **SmartCrawl** — Simplest UI, least overwhelming. Best for WPMU DEV ecosystem users. Generous free tier for schema. Weakest on analytics integration and IndexNow.
- **Yoast** — Most beginner-friendly (traffic-light system). Most detailed readability. Locks more behind Pro.
- **Rank Math** — Most feature-rich free tier. Best analytics integration. Most focus keywords. Rapidly adding AI-era features.
smartcrawl/redirects.md
+126
View File
@@ -0,0 +1,126 @@
# Redirects
SmartCrawl's Redirects module manages URL redirection from within WordPress, without editing `.htaccess` or server config. Found under Advanced Tools > Redirects.
## Redirect Types
| Code | Type | When to Use |
|------|------|-------------|
| **301** | Permanent | Page permanently moved. Passes ~90-99% of link equity. Default choice. |
| **302** | Temporary | Page temporarily moved. Does not pass link equity permanently. Use for A/B tests, maintenance. |
| **307** | Temporary (method preserved) | Like 302 but preserves the HTTP method and body. Rare use case. |
**Default recommendation:** Always use **301** unless you have a specific reason for temporary.
## Creating Redirects
### Basic (Plain Text)
1. Go to SmartCrawl > Advanced Tools > Redirects
2. Click "Add Redirect"
3. Enter the **source URL** (old URL path, e.g., `/old-page/`)
4. Enter the **destination URL** (new URL, e.g., `/new-page/` or full URL)
5. Select redirect type (301/302/307)
6. Save
### Regex Pattern
Switch to "Regex" mode for pattern-based redirects:
```
Source: /blog/(\d{4})/(\d{2})/(.*)
Destination: /blog/$3
Type: 301
```
This redirects dated blog URLs to non-dated versions.
**Regex tips:**
- Test patterns on [regex101.com](https://regex101.com) before applying
- Use capture groups `()` and backreferences `$1`, `$2`, etc.
- Some users report regex patterns not working despite being valid — test thoroughly
### Wildcard Redirects
Use regex mode for wildcards:
```
Source: /old-section/(.*)
Destination: /new-section/$1
Type: 301
```
This redirects all URLs under `/old-section/` to `/new-section/` while preserving the path.
## Auto-Redirect Deleted Posts (v3.9.0+)
Enable this to automatically create a 301 redirect when a post or page is deleted. The redirect points to:
- The parent page (if it was a child page)
- The homepage (if no logical parent)
**Recommendation:** Enable this to prevent 404s when content is removed.
## Bulk Import/Export
### Export
- SmartCrawl exports redirects as JSON
- Useful for backing up redirects before changes
### Import
- Import redirects from JSON file
- Useful when migrating between sites or restoring from backup
### Bulk Edit
- Change redirect types in bulk (e.g., convert all 302s to 301s)
- Delete all redirects at once (use with caution)
## Pro Features
### Location-Based Redirects
With SmartCrawl Pro + MaxMind GeoIP database:
- Redirect visitors based on their country or region
- Example: Redirect Canadian visitors to a `.ca` domain
- Requires MaxMind DB configuration in settings
## When to Use Redirects
| Scenario | Action |
|----------|--------|
| Page URL changed | 301 from old URL to new URL |
| Page deleted, replacement exists | 301 to the replacement page |
| Page deleted, no replacement | 301 to the most relevant parent or category page |
| Site migration (domain change) | 301 all old URLs to new domain equivalents |
| HTTP to HTTPS migration | 301 all HTTP URLs to HTTPS (better handled at server level) |
| www to non-www (or vice versa) | 301 (better handled at server level) |
| Temporary maintenance | 302 to a maintenance page |
| A/B testing | 302 to the test variant |
| Consolidating duplicate content | 301 all duplicates to the canonical version |
## Common Redirect Chains to Avoid
A redirect chain is when URL A redirects to URL B, which redirects to URL C. This wastes crawl budget and dilutes link equity.
**Bad:** `/old-page/` → `/newer-page/` → `/newest-page/`
**Good:** `/old-page/` → `/newest-page/` (and `/newer-page/` → `/newest-page/`)
When adding a new redirect, check if the destination already has a redirect pointing elsewhere. If so, update the chain to point directly to the final destination.
## Known Limitations
| Issue | Workaround |
|-------|-----------|
| Cannot reorder redirects | Delete and recreate in the desired order |
| Regex patterns sometimes fail | Test on regex101.com first; try simpler patterns |
| No 404 monitoring (Free) | Pro includes a site crawler that detects 404s |
| No redirect chain detection | Manually audit for chains |
| Large redirect lists can be slow | Consider moving high-volume redirects to `.htaccess` or server config |
## Best Practices
1. **Always redirect, never delete** — A 404 loses all SEO value the old URL had
2. **Redirect to the most relevant page** — not always the homepage
3. **Audit redirects quarterly** — remove redirects for URLs that no longer receive traffic
4. **Keep redirect lists manageable** — if you have 500+ redirects, consider server-level handling
5. **Test after creating** — visit the old URL in an incognito window to verify the redirect works
6. **Check redirect response code** — use [httpstatus.io](https://httpstatus.io) or browser dev tools Network tab
smartcrawl/schema-markup.md
+190
View File
@@ -0,0 +1,190 @@
# Schema / Structured Data
SmartCrawl provides both pre-built schema types and a custom schema builder. Schema markup generates rich results in search (star ratings, FAQ dropdowns, event dates, breadcrumbs, etc.) that significantly increase SERP visibility and click-through rates.
## Pre-Built Schema Types
SmartCrawl includes the following ready-to-use types:
| Schema Type | Rich Result | Best For |
|-------------|-------------|----------|
| **Article** | Article metadata | Blog posts, news articles |
| **Web Page** | Page metadata | Static pages |
| **FAQ** | Expandable Q&A in SERPs | FAQ pages, service pages with Q&A sections |
| **HowTo** | Step-by-step instructions in SERPs | Tutorial content, guides |
| **Product** | Price, availability, rating | WooCommerce products |
| **Local Business** | Knowledge panel, maps | Business homepages, location pages |
| **Recipe** | Rich recipe card | Food/recipe content |
| **Job Posting** | Job listing in Google Jobs | Career/hiring pages |
| **Movie** | Movie info panel | Entertainment/review sites |
| **Course** | Course listing | Educational offerings |
| **Book** | Book info panel | Book reviews, author sites |
| **Software Application** | App info | Software product pages |
| **Event** | Date, time, location in SERPs | Event listing pages |
| **Rating / Review** | Star ratings | Review pages (use only with genuine reviews) |
| **Video** | Video thumbnail in SERPs | Pages with embedded video |
| **Person** | Person knowledge panel | About pages, team pages |
| **Organization** | Org knowledge panel | Company about pages |
## Custom Schema Type Builder
SmartCrawl includes a **free** custom schema builder for creating schema types not in the pre-built list. Features:
- Define unlimited custom schema types
- Three property structures: **Simple**, **Nested**, or **Collection**
- Associate custom schemas with specific posts, pages, or taxonomies
- Full JSON-LD output
## Priority Schema Types to Implement
### Tier 1 — Every site should have these
1. **Organization** — Set globally in SmartCrawl's Schema settings
- Business name, logo URL, contact info
- Social media profile URLs (`sameAs`)
- Founding date, description
2. **LocalBusiness** (for businesses with a physical location or service area)
- 60+ subtypes available (e.g., `MotorcycleDealer`, `EducationalOrganization`, `ProfessionalService`)
- Full NAP: name, street address, city, state, ZIP, country
- Telephone, email
- Opening hours specification
- Geo coordinates (latitude, longitude)
- Area served
- Price range
3. **BreadcrumbList** — Automatic when Breadcrumbs module is enabled
### Tier 2 — Add where applicable
4. **FAQ** — Any page with Q&A content
- Can generate expandable FAQ directly in search results
- Each question/answer pair is a separate `Question` entity
- High-visibility rich result
5. **Event** — For event-based businesses
- Start date, end date, location
- Offers (price, availability, URL)
- Performer/organizer
- Shows date/time/location directly in SERPs
6. **Course** — For educational offerings
- Course name, description, provider
- Duration, schedule
- Price, enrollment URL
7. **Article / BlogPosting** — For blog content (usually default)
### Tier 3 — Situational
8. **Product** — WooCommerce (auto-handled)
9. **Video** — Pages with embedded video content
10. **HowTo** — Instructional/tutorial content
11. **Person** — Individual portfolio/about pages
## LocalBusiness Schema Setup
This is the most important schema for local businesses. Set it up in SmartCrawl > Schema > Types.
### Required Properties
```json
{
"@context": "https://schema.org",
"@type": "LocalBusiness",
"name": "Alaska Safe Riders",
"address": {
"@type": "PostalAddress",
"streetAddress": "123 Main St",
"addressLocality": "Anchorage",
"addressRegion": "AK",
"postalCode": "99501",
"addressCountry": "US"
},
"telephone": "+1-907-555-0123",
"url": "https://alaskasaferiders.org"
}
```
### Recommended Additional Properties
```json
{
"openingHoursSpecification": [
{
"@type": "OpeningHoursSpecification",
"dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
"opens": "09:00",
"closes": "17:00"
}
],
"geo": {
"@type": "GeoCoordinates",
"latitude": 61.2181,
"longitude": -149.9003
},
"areaServed": {
"@type": "State",
"name": "Alaska"
},
"priceRange": "$$",
"image": "https://example.com/logo.png",
"sameAs": [
"https://www.facebook.com/yourbusiness",
"https://www.instagram.com/yourbusiness"
]
}
```
### LocalBusiness Subtypes
SmartCrawl supports 60+ subtypes. Choose the most specific one that applies:
| Category | Examples |
|----------|----------|
| Automotive | `AutoDealer`, `AutoRepair`, `MotorcycleDealer`, `MotorcycleRepair` |
| Education | `EducationalOrganization`, `School`, `DrivingSchool` |
| Professional | `ProfessionalService`, `Consultant`, `LegalService` |
| Health | `MedicalBusiness`, `Dentist`, `Physician` |
| Food | `Restaurant`, `Bakery`, `BarOrPub`, `CafeOrCoffeeShop` |
| Entertainment | `EntertainmentBusiness`, `MovieTheater`, `NightClub` |
| Home | `HomeAndConstructionBusiness`, `Electrician`, `Plumber` |
| Store | `Store`, `ClothingStore`, `HardwareStore`, `SportingGoodsStore` |
## WooCommerce Product Schema
When enabled, SmartCrawl:
- **Replaces** WooCommerce's default schema (avoids duplicates)
- Auto-fetches product reviews and aggregate ratings
- Supports both simple and variable products
- Includes MPN, SKU, `priceValidUntil`
- Adds `offers` with price, currency, availability
Enable via: **SmartCrawl > Schema > WooCommerce Product Open Graph**
## Person Schema
As of v3.15.0, Person Schema can be limited to specific pages when Organization Schema is enabled globally. Useful for:
- Team member pages
- Author bio pages
- Individual portfolio sites (e.g., Chelsea Paige Mann)
## Validation
**Always validate schema after deployment:**
1. [Google Rich Results Test](https://search.google.com/test/rich-results) — checks if your schema qualifies for rich results
2. [Schema.org Validator](https://validator.schema.org/) — validates JSON-LD syntax
3. Google Search Console > Enhancements — monitors schema errors across your site over time
## Common Schema Mistakes
| Mistake | Fix |
|---------|-----|
| Duplicate schema from multiple plugins | Deactivate other SEO plugins' schema output |
| Using Review schema without genuine reviews | Only add if you have real, verifiable reviews |
| Missing required properties | Check Google's [structured data documentation](https://developers.google.com/search/docs/advanced/structured-data/) for requirements per type |
| Wrong LocalBusiness subtype | Use the most specific applicable type |
| Schema on pages it doesn't apply to | Only add schema types relevant to the page content |
smartcrawl/sitemaps.md
+108
View File
@@ -0,0 +1,108 @@
# Sitemaps
SmartCrawl generates three types of sitemaps: XML, Google News, and Image. All are configured under the Sitemap module.
## XML Sitemap
### Configuration
| Setting | Recommended Value |
|---------|------------------|
| Enable XML Sitemap | Yes |
| Post types included | Posts, Pages, Products, public custom post types |
| Taxonomies included | Categories (yes), Tags (only if indexed), custom taxonomies |
| Max URLs per file | Default (auto-splits into multiple files) |
| Notify search engines | Automatic |
### Access
Your sitemap is at: `https://yoursite.com/sitemap.xml`
SmartCrawl auto-generates a sitemap index that links to individual sitemaps per post type and taxonomy.
### Exclusions
Exclude specific content by:
- **Post/page ID** — Enter IDs in the exclusion list
- **Custom URLs** — Add specific URLs to exclude
- **Post type** — Uncheck entire post types from the include list
**Important:** If you set a page to `noindex`, also exclude it from the sitemap. SmartCrawl does **not** do this automatically.
### Limitation
SmartCrawl limits sitemaps to **1,000 most recent posts** per post type to prevent memory errors on large sites. If you have more than 1,000 posts, older content may not appear in the sitemap.
## Google News Sitemap
Enable this only if the site publishes news-style content that qualifies for Google News.
### Requirements for Google News
- Content must be timely, original news articles
- Published within the last 2 days (Google News requirement)
- Site should be registered with Google News Publisher Center
### Configuration
- Enable the Google News Sitemap toggle
- Select which post types to include (usually just Posts)
- Verify at `https://yoursite.com/news-sitemap.xml`
## Image Sitemap
One-click enable. Tells Google about images on your pages for Google Images indexing.
### When to Enable
- Sites with significant visual content (portfolios, galleries, products)
- Sites where image search traffic is valuable
- Always enable for WooCommerce sites (product images)
### What It Includes
SmartCrawl adds image entries to your existing XML sitemap (not a separate file). Each page entry includes its images with:
- Image URL
- Image title
- Image caption (if set)
## Sitemap Submission
### Google Search Console
1. Go to Search Console > Sitemaps
2. Enter `sitemap.xml` in the "Add a new sitemap" field
3. Click Submit
4. Verify status shows "Success" after Google fetches it
### Bing Webmaster Tools
1. Go to Bing Webmaster Tools > Sitemaps
2. Submit `https://yoursite.com/sitemap.xml`
### robots.txt
Add a sitemap directive to robots.txt (use full absolute URL):
```
Sitemap: https://yoursite.com/sitemap.xml
```
## After Making Changes
When you add/remove content or change sitemap settings:
1. Use the **"New Crawl" button** in SmartCrawl's sitemap tab to notify Google
2. Or wait for automatic notification (if set to Automatic mode)
3. Verify the updated sitemap at `yoursite.com/sitemap.xml`
4. Check Google Search Console > Sitemaps for any errors
## Troubleshooting
| Issue | Fix |
|-------|-----|
| Sitemap returns 404 | Flush permalinks (Settings > Permalinks > Save) |
| Post type missing from sitemap | Check SmartCrawl Sitemap settings — ensure the post type is included |
| Noindexed pages appearing in sitemap | Manually exclude them by ID — SmartCrawl doesn't auto-exclude noindexed content |
| WPML duplicate URLs | Known issue — duplicate homepage URLs in sitemap when using WPML |
| Sitemap too large / memory error | SmartCrawl limits to 1,000 posts — contact WPMU DEV support for large sites |
smartcrawl/social-og-twitter.md
+143
View File
@@ -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. |
smartcrawl/titles-and-meta.md
+190
View File
@@ -0,0 +1,190 @@
# Titles & Meta Descriptions
SmartCrawl's Titles & Meta module controls how every page on your site appears in search results and browser tabs. It uses a macro/variable system for global templates with per-post overrides.
## Template Macros
SmartCrawl uses `%%variable%%` syntax. The full list is accessible via the **"Browse Macros"** button in the Titles & Meta admin screen.
### Core Macros
| Macro | Output |
|-------|--------|
| `%%title%%` | Post/page title |
| `%%sitename%%` | Site name (from Settings > General) |
| `%%sep%%` | Separator character (configurable) |
| `%%excerpt%%` | Post excerpt (auto-generated if not set) |
| `%%excerpt_only%%` | Excerpt only — no auto-generation fallback |
| `%%category%%` | Post primary category |
| `%%tag%%` | Post tags |
| `%%term_title%%` | Term/taxonomy title |
| `%%term_description%%` | Term description |
### Date & Time Macros
| Macro | Output |
|-------|--------|
| `%%date%%` | Post published date |
| `%%modified%%` | Post last modified date |
| `%%currenttime%%` | Current time |
| `%%currentdate%%` | Current date |
| `%%currentday%%` | Current day |
| `%%currentmonth%%` | Current month |
| `%%currentyear%%` | Current year |
### Pagination Macros
| Macro | Output |
|-------|--------|
| `%%page%%` | Page number |
| `%%pagenumber%%` | Current page number |
| `%%pagetotal%%` | Total pages |
| `%%spell_pagenumber%%` | Page number in words ("Page Two of Five") |
| `%%spell_pagetotal%%` | Total pages in words |
### Author & Post Macros
| Macro | Output |
|-------|--------|
| `%%name%%` | Author display name |
| `%%userid%%` | Author user ID |
| `%%id%%` | Post ID |
| `%%pt_single%%` | Post type singular name |
| `%%pt_plural%%` | Post type plural name |
### Special Macros
| Macro | Output |
|-------|--------|
| `%%searchphrase%%` | Search query (for search results page) |
| Custom field macros | Supported with uppercase (v3.11.0+) |
> Additional "dynamic macros" exist for edge cases that do not appear in the Browse Macros list. These are documented in the WPMU DEV support forums.
## Global vs Per-Post Settings
| Level | Scope | How It Works |
|-------|-------|-------------|
| **Global template** | Per post type, per taxonomy, archives, special pages | Set once, applies everywhere via macros |
| **Per-post override** | Individual post/page | Entered in the SmartCrawl meta box in the editor — overrides the global template |
### When to Use Each
- **Global template:** Set it and forget it. Works well for blogs, archives, and consistent content types.
- **Per-post override:** Use for every important page. Homepage, service pages, key landing pages, and high-value blog posts should all have hand-crafted titles and descriptions.
## Recommended Title Templates
### Homepage
```
%%sitename%% %%sep%% [Your primary value proposition]
```
Example output: `Alaska Safe Riders | Motorcycle Safety Courses in Anchorage, AK`
### Posts (Blog)
```
%%title%% %%sep%% %%sitename%%
```
Example output: `What to Wear to a Motorcycle Safety Course | Alaska Safe Riders`
### Pages
```
%%title%% %%sep%% %%sitename%%
```
Override per-page for service pages with keyword-optimized titles.
### Categories
```
%%term_title%% %%sep%% %%sitename%%
```
### Author Archives
```
Posts by %%name%% %%sep%% %%sitename%%
```
(Consider noindexing author archives on single-author sites)
### Search Results
```
Search Results for "%%searchphrase%%" %%sep%% %%sitename%%
```
(Always noindex search results pages)
### 404 Page
```
Page Not Found %%sep%% %%sitename%%
```
## Title Tag Best Practices
- **Length:** 50-60 characters (Google truncates at ~580px pixel width)
- **Primary keyword placement:** As close to the beginning as possible
- **Every page must have a unique title** — duplicates confuse Google
- **Include brand name** at the end (builds brand recognition in SERPs)
- **Do not keyword-stuff** — one primary keyword is enough
- **Use power words for CTR:** "Best", "Guide", "Free", numbers, parentheses
### Good vs Bad Examples
| Bad | Good |
|-----|------|
| `Home - My Website` | `Motorcycle Safety Courses Anchorage, AK \| Alaska Safe Riders` |
| `Services` | `Event Management & Roster Tracking \| ASR Events Manager` |
| `Blog Post Title Here \| Category \| Website Name` | `What to Expect at a Basic Rider Course \| Alaska Safe Riders` |
## Meta Description Best Practices
- **Length:** 150-160 characters (Google truncates unpredictably above this)
- **Include primary keyword** naturally (Google bolds matching terms)
- **Include a call to action:** "Register today", "Learn more", "Contact us"
- **Include differentiators:** Pricing, location, certifications, experience
- **Hand-craft descriptions** for important pages — auto-generated ones rarely perform well
- **Google rewrites ~60% of meta descriptions** but good ones are kept and improve CTR
### Quality Indicators in SmartCrawl
SmartCrawl's SEO status column on post/page lists uses color-coded indicators:
| Color | Meaning |
|-------|---------|
| Green | Description is 120-160 characters, hand-crafted |
| Yellow | Description exists but is outside optimal range or auto-generated |
| Red | No description set |
## Separator Character
Set in Titles & Meta > General. Common choices:
| Separator | Look |
|-----------|------|
| `\|` (pipe) | `Page Title \| Site Name` |
| `—` (em dash) | `Page Title — Site Name` |
| `-` (hyphen) | `Page Title - Site Name` |
| `»` | `Page Title » Site Name` |
**Recommendation:** Use `|` or `—` for a clean, modern appearance.
## Noindex Recommendations
Set these in the Titles & Meta module per post type/taxonomy:
| Content Type | Recommendation | Reason |
|--------------|---------------|--------|
| Tag archives | Noindex | Usually thin content, duplicate of category archives |
| Author archives | Noindex (single-author sites) | Duplicate of main blog page |
| Date archives | Noindex | Thin content, duplicate |
| Search results | Noindex | Dynamic, no SEO value |
| Paginated archives | Noindex | Thin duplicate content |
| Media attachment pages | Noindex | Single image on a page, no value |
| Thank you pages | Noindex | No search value |
## Post Type Configuration
Check **Settings > Advanced > Post Types** to ensure all relevant content types are enabled:
- Posts and Pages (default)
- WooCommerce Products (if applicable)
- Portfolio items
- Any custom post types
**If a post type is not enabled, its pages will not appear in sitemaps and will not get SmartCrawl meta box in the editor.**