On-Page SEO Audit — Tool Reference

1. The checks

112 checks across 12 categories. Live checks run today and produce a real pass/fail/warn verdict. Pending checks are on the roadmap — each has a specific, named reason it isn't automated yet, not just "not done."

1. HTML Metadata 11/11 live

2. URL Structure 7/7 live

3. Heading Structure 8/8 live

4. Content Quality & Readability 11/15 live

5. Images 13/13 live

6. Internal Linking 11/12 live

7. External Linking 12/13 live

8. Video & Audio Content 1/1 live

9. Structured Data & Schema Infrastructure 9/11 live

10. Mobile Infrastructure & Mobile-First Indexing 5/6 live

11. Core Web Vitals & Performance Engineering 10/10 live

12. Crawlability, Indexability & Architecture 5/5 live

2. Data we collect

Everything below comes from the page itself, its directly-linked resources, and — only when explicitly enabled — a site-wide crawl or an external performance API. Nothing is collected beyond what a specific check needs.

Every audit, single page

• Fetch data — final URL after redirects, HTTP status code, response headers, response time to first byte (TTFB), raw HTML
• Parsed structure — title tag(s), every meta tag (name/property → content), the full heading outline (level, text, id), every image (src, alt, dimensions, loading attribute), every link (href, anchor text, rel, target, internal vs. external), every JSON-LD structured-data block, canonical URL, robots meta, HTML lang attribute, charset, viewport tag
• Directly-linked resources — robots.txt, the XML sitemap, the favicon, the og:image, individual image files (for size/format checks), CSS and JS assets (for size, minification, and caching checks) — each fetched only if the relevant check needs it

Site-wide audits only (--site-wide)

• Every page reachable from the entry URL, up to a configured page/depth limit, crawled via Crawl4AI
• The full internal link graph — which pages link to which, and with what anchor text
• A second crawl rendered with a Googlebot-Smartphone user agent at a mobile viewport, for mobile-parity checks

Performance checks only (when PAGESPEED_API_KEY is set)

• Real-user Core Web Vitals field data (LCP, INP, CLS) from Google PageSpeed Insights / the Chrome UX Report

3. How results are judged (KPIs / thresholds)

Every number below is a config value, not something buried in code — thresholds can be tuned per client or industry without touching the check logic. This is the actual configuration the tool ships with.

Each individual result also carries a priority (High / Medium / Low, from the specification) which combines with its pass/fail/warn status into a final severity — Critical, High, Medium, or Low — used to sort recommendations by what to fix first.

4. Output formats

Every audit produces the same underlying result set — an overall score, per-category pass/fail/warn counts, and every individual check's evidence — rendered into one of three formats.

Console output (excerpt)

======================================================================
ON-PAGE SEO AUDIT REPORT (Phase 1 — rule-based checks only)
======================================================================
URL:   https://example.com/
Score: 75.5/100  (47 scored / 103 total checks)

-- 1. HTML Metadata (3/11 passed) --
  [✗] 1.1    Title Tag                                    FAIL
  [✓] 1.2    Meta Description                              PASS
  [!] 1.8    Open Graph Meta Tags                           WARN
  ...

======================================================================
RECOMMENDATIONS (16)
======================================================================

1. [Critical] 1.1 — Title Tag
   Fix: Write one unique, accurate <title> per page, ideally 50-60 characters.
   Why: The title is one of the strongest on-page SEO signals and directly
        affects click-through rate from search results.

JSON report shape

{
  "url": "...", "final_url": "...", "audit_run_id": "...",
  "overall_score": { "score": 75.5, "scored_checks": 47, "total_checks": 103 },
  "category_scores": {
    "1. HTML Metadata": { "pass": 3, "fail": 5, "warn": 2, "other": 1, "total": 11 },
    ...
  },
  "results": [
    {
      "check_id": "metadata.title_tag", "doc_ref": "1.1", "name": "Title Tag",
      "category": "1. HTML Metadata", "priority": "High", "status": "FAIL",
      "message": "Title is 14 characters, shorter than the 50-60 best-practice band.",
      "evidence": { "title": "...", "length": 14 }
    },
    ...
  ]
}

Markdown report (excerpt)

# On-Page SEO Audit — https://example.com/

**Score:** 75.5/100 (47 scored checks, 103 total)
**Run ID:** 44eb1b7d-fd50-4f4a-8c1f-a6bd7d4ed5d9

## Recommendations

### [Critical] 1.1 — Title Tag
- **Recommendation:** Write one unique, accurate <title> per page, ideally 50-60 characters.
- **Why it matters:** The title is one of the strongest on-page SEO signals and
  directly affects click-through rate from search results.

## All Checks

### 1. HTML Metadata
- ❌ **1.1 Title Tag** — Title is 14 characters, shorter than the 50-60 best-practice band.
- ✅ **1.2 Meta Description** — Meta description is 152 characters, within the best-practice band.