On-Page SEO Audit

Analyze source code files for on-page SEO issues and produce a clear, actionable markdown report. The goal is to catch real problems that hurt search rankings — not to nitpick or generate noise.

How to run an audit

1. Identify the files to audit. If the user points to specific files, use those. If they say "audit my site" or similar, look for page-level files — things like index.html, Next.js pages (app/**/page.tsx, pages/**/*.tsx), or layout files. Use Glob to find them.
2. Read each file and check against the checklist below.
3. Produce the report in the format described at the bottom.

What to check

Work through each section for every page file. Not every check applies to every file — use judgment. A shared <Header> component won't have a <title> tag, and that's fine.

Title tag

The <title> element (or metadata.title in Next.js) is the single most important on-page SEO signal.

Check for:

• Missing title entirely
• Title that's too short (under 20 characters) or too long (over 60 characters) — search engines truncate long titles
• Generic/meaningless titles like "Home", "Page", "Untitled", or the framework default
• Duplicate titles across pages (if auditing multiple pages)

Why it matters: The title tag is displayed as the clickable headline in search results. A clear, descriptive title with relevant keywords directly affects click-through rate and ranking.

Meta description

The <meta name="description"> tag (or metadata.description in Next.js).

Check for:

• Missing entirely — search engines will auto-generate one, but it's usually worse
• Too short (under 50 characters) or too long (over 160 characters)
• Doesn't summarize the page content or include relevant keywords
• Duplicate descriptions across pages

Why it matters: While not a direct ranking factor, the meta description appears as the snippet in search results and heavily influences click-through rate.

Heading structure

The hierarchy of <h1> through <h6> tags.

Check for:

• Missing <h1> — every page should have exactly one
• Multiple <h1> tags on the same page
• Skipped heading levels (e.g., <h1> followed by <h3> with no <h2>)
• Empty headings or headings with only icons/images
• Headings used purely for styling rather than structure (hard to detect in code, but flag if obvious)

Why it matters: Search engines use heading hierarchy to understand page structure and topic importance. A clean heading outline helps crawlers identify what the page is about.

Image alt text

The alt attribute on <img> tags and Next.js <Image> components.

Check for:

• Missing alt attribute entirely (different from alt="" which is intentional for decorative images)
• Very generic alt text like "image", "photo", "picture", "screenshot", "img1"
• Alt text that's just the filename (e.g., "IMG_2847.jpg", "hero-banner.png")
• Excessively long alt text (over 125 characters) — keep it concise
• Images that appear to be content-relevant but have alt=""

Why it matters: Image alt text helps search engines understand image content, enables image search traffic, and is also an accessibility requirement. Good alt text describes what the image shows in context.

Internal links

Links between pages within the site.

Check for:

• Pages with no internal links pointing to other pages (orphan pages)
• Links using non-descriptive anchor text like "click here", "read more", "learn more", "link" — the anchor text should describe the destination
• Broken-looking links (relative paths that seem wrong, href="#", href="", javascript:void(0))
• Important pages that are deeply nested (many clicks from the home page)

Why it matters: Internal links distribute page authority and help search engines discover and understand the relationship between pages. Descriptive anchor text tells crawlers what the linked page is about.

Open Graph & social meta tags

<meta property="og:*"> and <meta name="twitter:*"> tags.

Check for:

• Missing og:title, og:description, og:image — these control how the page appears when shared on social media
• og:image pointing to a path that might not resolve (relative paths without a base URL)
• Missing twitter:card if the site is likely shared on X/Twitter

Why it matters: While not a direct Google ranking factor, social sharing drives traffic. Pages shared without proper OG tags look unprofessional and get fewer clicks.

Canonical URL

The <link rel="canonical"> tag.

Check for:

• Missing on pages that could have duplicate URLs (e.g., pages accessible with and without trailing slashes, with query parameters)
• Self-referencing canonical is fine and expected
• Canonical pointing to a different domain (flag as suspicious unless intentional)

Why it matters: Canonical tags prevent duplicate content issues by telling search engines which version of a page is the "official" one.

Structured data hints

Look for JSON-LD (<script type="application/ld+json">), microdata, or RDFa.

Check for:

• Not a hard requirement, but note if the page type would benefit from structured data (e.g., product pages, articles, FAQs, recipes, events)
• If structured data exists, check for obvious issues like missing required fields

Why it matters: Structured data enables rich snippets in search results (star ratings, FAQ dropdowns, product prices) which significantly boost click-through rate.

Report format

Structure the report as follows. Omit sections where nothing was found — a clean report is more useful than one padded with "no issues found" for every category.

# SEO Audit Report: [page name or file path]

## Summary
[1-2 sentences: overall SEO health and the most impactful issues to fix first]

## Critical Issues
[Issues that are very likely hurting search rankings right now]

### [Issue title]
- **File:** `path/to/file.tsx` (line X)
- **Problem:** [What's wrong]
- **Impact:** [Why this hurts SEO]
- **Fix:** [Specific suggestion, with code snippet if helpful]

## Warnings
[Issues that could be improved but aren't dealbreakers]

### [Issue title]
- **File:** `path/to/file.tsx` (line X)
- **Problem:** [What's wrong]
- **Impact:** [Why this matters]
- **Fix:** [Suggestion]

## Suggestions
[Nice-to-haves and optimizations]

- [Brief suggestion with rationale]

Severity guidelines

• Critical: Missing title tag, missing h1, missing all alt text on content images, no meta description on key landing pages
• Warning: Title too long/short, generic alt text, non-descriptive link text, missing OG tags, skipped heading levels
• Suggestion: Adding structured data, improving meta description wording, adding canonical tags as a precaution

Auditing multiple pages

When auditing a whole site (multiple page files), add a summary table at the top:

# Site-Wide SEO Audit

## Overview

| Page | Critical | Warnings | Suggestions |
|------|----------|----------|-------------|
| `/` (home) | 1 | 3 | 2 |
| `/about` | 0 | 2 | 1 |
| `/blog/[slug]` | 2 | 1 | 3 |

## Page-by-page results
[Individual reports follow]

Next.js-specific notes

When auditing Next.js App Router projects, be aware of:

• Metadata API: Title and meta description are often set via export const metadata or generateMetadata() in page.tsx or layout.tsx, not as HTML tags. Check both.
• Layouts: <html>, <head>, and root structure live in layout.tsx. A missing <h1> in page.tsx isn't necessarily a problem if the layout provides it — but usually the page should have its own <h1>.
• Image component: Next.js <Image> requires alt as a prop. If it's missing, it'll throw a build error — but check for empty strings (alt="") on content images.
• Dynamic routes: [slug] pages get their content at runtime, so the template might not have literal title/description text. Check that generateMetadata() is implemented and uses the dynamic data.
• next/head: In Pages Router projects, metadata is set via <Head> from next/head. Check for this pattern too.