# 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