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,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