# SEO Audit

The SEO audit scans your site settings and every page, then returns a scored health report with educational explanations and fix suggestions. Run it before deploying to catch issues, or anytime with `/seo` to check your site's search engine readiness.

## How to run it

Type `/seo` in any supported agent to run the full audit. Pass an optional scope to narrow the check:

```bash
/seo                  # Full audit — settings + all pages + cross-page checks
/seo settings         # Settings-level checks only
/seo pages            # Page-level checks only
/seo /about           # Audit a single page by slug
```

The audit also runs automatically during `sitemd build` and `sitemd deploy`, printing a compact score summary to the console. During agent-assisted deploys, the full report is presented with the option to fix issues before proceeding.

### MCP tool

Agents can call `sitemd_seo_audit` directly:

```json
{
  "scope": "all",
  "slug": "/docs/getting-started"
}
```

Both `scope` and `slug` are optional. When `slug` is provided, only that page is audited.

## How scoring works

The audit produces a score from 0 to 100 based on a weighted pass rate. Errors carry 3× weight, warnings 2×, and info-level checks 1×. A site that passes all error and warning checks scores in the 90s even with some info items flagged.

| Score | Assessment |
|---|---|
| 90–100 | Excellent — your SEO is in great shape |
| 70–89 | Good — a few things to tighten up |
| 50–69 | Needs attention — several issues affecting your visibility |
| Below 50 | Critical — significant SEO gaps to address |

## What it checks

The audit runs three categories of checks: site-level settings, per-page metadata, and cross-page patterns.

### Settings checks

These verify your `settings/seo.md` and `settings/meta.md` configuration. Every field in `seo.md` is covered.

| Check | Severity | What it looks for |
|---|---|---|
| Site URL | Error | `url` in meta.md is missing or still a placeholder. Canonical URLs, sitemaps, and OG tags all need your real domain. |
| Site description | Warning | Description in meta.md is missing or under 20 characters. This is the default search result snippet. |
| OG image | Warning | `ogImage` set to "none". Social shares show a blank card without an image. |
| Favicon | Info | Using auto-generated letter favicon instead of a custom brand image. |
| Structured data | Warning | `structuredData` disabled. Prevents rich results in search (FAQ dropdowns, article cards). |
| IndexNow | Info | `indexNow` disabled. Search engines won't be notified immediately on deploy. |
| Default author | Info | No `defaultAuthor` configured. Blog posts appear authorless in schema, weakening E-E-A-T signals. |
| Twitter handle | Info | No `twitterHandle` set. Shared content on X won't attribute back to your profile. |
| Organization identity | Info | `orgName` or `orgLogo` missing when structured data is on. Weakens Knowledge Panel eligibility. |
| llms.txt | Info | `llmsTxt` disabled. AI tools can't discover your content for citations. |
| Markdown output | Info | `markdownOutput` disabled. AI crawlers prefer structured text over HTML. |
| AI crawlers | Info | `allowAICrawlers` disabled. Blocks your content from AI-powered search and recommendations. |

### Page checks

These run on every page (or a single page when a slug is provided).

| Check | Severity | What it looks for |
|---|---|---|
| Missing title | Error | No `title` in frontmatter. Search results show the raw URL instead. |
| Title length | Warning | Formatted title over 60 or under 10 characters. Google truncates long titles; short ones are too vague to rank. |
| Double suffix | Warning | Title suffix appears twice (e.g. "About \| Site \| Site"). Wastes title space and looks like a bug. |
| Missing description | Warning | No description and none could be derived from content. Google picks a random sentence instead. |
| Description length | Warning | Description over 160 or under 50 characters. Long ones get truncated; short ones waste the click-through opportunity. |
| OG image missing | Warning | No page image and global `ogImage` is "none". Social shares show a text-only card. |
| Noindex flag | Info | Page has `robots: noindex`. Informational — confirms it's intentionally hidden from search. |
| Missing alt text | Warning | Images without alt text. Hurts accessibility and prevents Google from indexing images. |
| Heading hierarchy | Warning | No H1 heading found. Multiple `# headings` are auto-downgraded to SEO-safe `<h2>` elements — only a missing H1 is flagged. Use [`hidden:`](/docs/hidden-content) to add one without affecting the design. See [Headings](/docs/headings). |
| Broken links | Error | Internal links pointing to pages that don't exist. Dead ends for visitors and crawlers. |
| Thin content | Warning | Under 50 words of content (excludes homepage and auth pages). Unlikely to rank for any query. |

### Site-wide checks

These analyze patterns across all pages.

| Check | Severity | What it looks for |
|---|---|---|
| Duplicate titles | Warning | Multiple pages with identical formatted titles. Search engines can't decide which to rank. |
| Duplicate descriptions | Warning | Multiple pages sharing the same description. Each page needs a unique pitch. |
| Content freshness | Info | Pages with `updated` dates over 12 months old. Freshness is a ranking signal. |
| Schema coverage | Info | Pages using generic WebPage schema that could use BlogPosting, TechArticle, or FAQPage for rich results. |
| Blog author missing | Info | Blog posts without `author` and no `defaultAuthor` set. Weakens E-E-A-T trust signals. |

## How to fix issues

When running `/seo` interactively, the agent presents the full report and offers to fix issues. Fixes are grouped by file to minimize edits:

- **Settings issues** — uncomments and sets fields in `settings/seo.md` or `settings/meta.md`
- **Page meta issues** — adds or updates frontmatter fields (title, description, image)
- **Content issues** — describes what to change and offers to edit the page body
- **Cross-page issues** — identifies conflicting pages and rewrites titles or descriptions to be unique

After fixes, the agent offers to re-run the audit to verify the updated score.

## Pre-deploy integration

The SEO audit runs automatically at two points in the deploy flow:

1. **CLI** — `sitemd build` and `sitemd deploy` print a one-line score summary to the console after building. Errors are listed individually. The build and deploy always complete — the CLI output is informational only.

2. **Agent-assisted deploy** — when deploying via the `/deploy` skill, the agent runs `sitemd_seo_audit` and presents the full report before deploying. You choose whether to fix issues or skip and continue.

The `sitemd_deploy` MCP tool also includes the full `seoReport` in its response, so any agent orchestrating a deploy can present the results.

## Related

- [SEO](/docs/seo) — full SEO configuration reference
- [SEO Preview](/docs/seo-preview) — visual preview of search results and social cards
- [Deploy](/docs/deploy) — how the deploy process works
- [Agent Skills](/docs/skills) — all available agent skills including `/seo`