# W3C HTML Guidelines (SEO-Relevant Subset) Reference for `seo-validate` Category 1 (HTML Semantics & W3C) and Category 2 (Meta & Open Graph). Sources: W3C HTML Living Standard (HTML5), WCAG 2.2, IETF RFC 5646 (BCP 47), Open Graph Protocol, Twitter Card spec. ## Document Structure ### DOCTYPE HTML5 §8.1.1 — the document MUST begin with `` (case-insensitive). Missing doctype triggers quirks mode in older browsers and breaks modern CSS behavior — effectively a HIGH-severity issue. ```html ... ... ``` ### lang attribute HTML5 §3.2.6 — the `` element SHOULD have a `lang` attribute using a BCP 47 language tag. - Required for screen reader pronunciation (WCAG 3.1.1). - Signals primary language to search engines. - Feeds into hreflang correctness checks. Valid examples: - `lang="en"` — English (generic) - `lang="en-US"` — English (United States) - `lang="pl"` — Polish - `lang="zh-Hant"` — Chinese (Traditional) Invalid examples (flag these): - `lang="en_US"` — underscore, not hyphen - `lang="english"` — not an ISO code - `lang="EN"` — case irrelevant per RFC but inconsistent; prefer lowercase ### charset HTML5 §4.2.5.5 — `` MUST appear in `` as early as possible, within the first 1024 bytes. UTF-8 is the only accepted encoding for new content. ```html ``` ### viewport Not formally W3C but required for mobile-first indexing: ```html ``` Missing viewport = mobile rendering breaks = Google ranks the page lower. ## Document Outline ### Heading hierarchy HTML5 §4.3.6 defines heading semantics. Current best practice: - **Exactly one `

` per page/route component. - Sequential levels: `h1` → `h2` → `h3`, never skip (e.g., `h1` → `h3`). - Semantic, not decorative: heading level should reflect content hierarchy, not visual size. Use CSS for styling. ### Landmarks HTML5 §4.3 + ARIA Landmarks. Every page should have at minimum: - `
` — site/page header - `
` — primary navigation - `
` — main content (exactly one per page) - `
` — site/page footer Optionally: `
`, `
` (requires accessible name), `
`. Using `
` for these is a WARN — semantic HTML aids both screen readers and AI/LLM parsers. ## Meta Tags ### Title HTML5 §4.2.2. Required element inside ``. - Recommended length: 50–60 characters including brand/separator. Google truncates at ~600 pixels (~50–60 chars). - Unique per page. - Format: `Primary Keyword - Brand` or `Primary Keyword | Secondary | Brand`. - Avoid keyword stuffing. ```html SEO Audit Tool - Free Analyzer | ExampleCo ``` ### Description HTML ``. - Recommended length: 150–160 characters. Google truncates at ~155 chars (mobile narrower). - Unique per page. - Include primary keyword naturally. - Write as a SERP call-to-action. ```html ``` ### Canonical HTML5 §4.2.4 + Google Search Central canonicalization. - Required on indexable pages. - Must be an absolute URL. - Self-referencing canonical on canonical version. - Points to preferred version when multiple URLs return the same content (tracking params, pagination, sort orders). ```html ``` #### Canonical + URL parameters Query parameters create duplicate URLs unless handled explicitly. After Google deprecated the Search Console URL Parameters tool (April 2022), the only remaining signals are `rel="canonical"`, `robots.txt`, and ``. Tracking parameters (`utm_source`, `utm_medium`, `utm_campaign`, `gclid`, `fbclid`, `msclkid`, `ref`): Every variant must canonical to the clean URL: ```html ``` Faceted navigation (filters, sort, pagination on category/product listing pages): ```html ``` For facet combinations that are NOT genuinely different content (e.g., `?sort=name` vs `?sort=price`), always canonical to the clean URL. For facets that ARE different content (e.g., `/products?category=shoes` is a distinct shoe listing), the facet URL itself is canonical. Search result pages (SRPs)**: Internal search results are thin, user-specific content. Google's Search Essentials explicitly lists SRPs as content to keep out of the index. Two valid strategies: ```html ``` ``` # Strategy B: robots.txt Disallow — blocks crawl entirely User-agent: * Disallow: /search?* Disallow: /?q= ``` Never combine Disallow + noindex — a disallowed URL will never be fetched, so the noindex directive is never read. Pagination: Modern Google treats paginated content as individual URLs. Each page self-canonicals: ```html ``` `rel="prev"` and `rel="next"` are deprecated as a Google signal (2019) but remain valid HTML and are used by other engines/accessibility tools. ### Robots Controls indexing and following per-page. ```html ``` `noindex` on production routes is a HIGH-severity finding unless explicitly intentional (admin pages, thank-you pages, search-results pages). ## Open Graph Protocol `https://ogp.me/` — used by Facebook, LinkedIn, Slack, Discord, Teams, WhatsApp. Required for rich social cards: ```html ``` Image specs: - Recommended: 1200×630 px (1.91:1 aspect ratio). - Maximum: 8 MB. - JPEG or PNG. WebP has limited platform support for OG. Relative URLs for `og:image` are a definitive WARN — many scrapers don't resolve them. ## Twitter Card ```html ``` When OG tags are present, Twitter falls back to them for most fields — but `twitter:card` is still required. ## hreflang RFC 5646 (BCP 47) language tags + ISO 3166-1 alpha-2 region codes. ### Format ``` [-] ``` Valid: - `en`, `en-US`, `en-GB`, `pl`, `pt-BR`, `zh-Hant`, `sr-Cyrl` Invalid: - `en_US` (underscore) - `EN-us` (case inconsistent — prefer lowercase language, uppercase region) - `english` (not a code) - `uk` is Ukrainian, not "UK English" (common confusion — `en-GB` is correct for British English) ### Implementation Every locale version MUST include hreflang for every other locale, including itself, plus `x-default`: ```html ``` ### Bidirectionality If page A links to page B via hreflang, page B MUST link back to page A. Broken bidirectionality is ignored by Google — a HIGH-severity issue. ### x-default Fallback for users whose language doesn't match any listed locale. Usually points to the default/main version (often English). ## Validation The W3C provides an online validator: https://validator.w3.org/ — but the `seo-validate` skill targets static source analysis, not rendered HTML validation. For runtime validation, use: - `html-validate` (npm) - `htmlhint` - Built-in linters in Next.js, Nuxt, Astro ## References - HTML Living Standard: https://html.spec.whatwg.org/ - WCAG 2.2: https://www.w3.org/TR/WCAG22/ - BCP 47 (RFC 5646): https://datatracker.ietf.org/doc/html/rfc5646 - ISO 3166-1: https://www.iso.org/iso-3166-country-codes.html - Open Graph Protocol: https://ogp.me/ - Google Search Central (title/description/canonical): https://developers.google.com/search/docs