sitemd.cc

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:

/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:

{
  "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: to add one without affecting the design. See 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:

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.