# SEO Guidelines ## Document Structure - One `

` per page — main topic/title - Heading hierarchy: h1 → h2 → h3 → h4, never skip levels - Use semantic HTML elements: `
`, `
`, `
`, `
`, `
`, `
` - `` must be unique per page, under 60 characters - `<meta name="description">` must be unique per page, under 160 characters - Set `lang` attribute on `<html>` tag ## Navigation & Links - Breadcrumb inside `<nav>` tag for Google recognition - Use descriptive anchor text — never "click here" - Internal links use relative paths - External links use `rel="noopener"` when opening new tab - Site name links to homepage ## Images - All `<img>` must have `alt` attribute - Descriptive `alt` text — what the image shows, not "image of" - Use `width` and `height` attributes to prevent layout shift - Use `loading="lazy"` for below-fold images ## Structured Data - Breadcrumb: use `<nav aria-label="breadcrumb">` — separate `<nav>` from main navigation - Article/post pages: one `<article>` wrapping main content - Use Schema.org JSON-LD in `<head>` for: - `BreadcrumbList` on pages with breadcrumbs - `WebSite` with `SearchAction` on homepage - `Article` or `DefinedTerm` on content pages ## Meta Tags ```html <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="description" content="Page description here" /> <link rel="canonical" href="https://example.com/page/" /> ``` ## Open Graph & Social ```html <meta property="og:title" content="Page Title" /> <meta property="og:description" content="Page description" /> <meta property="og:type" content="website" /> <meta property="og:url" content="https://example.com/page/" /> <meta property="og:image" content="https://example.com/image.jpg" /> ``` ## Performance (SEO Impact) - No render-blocking resources above fold - CSS in single file, no unused CSS - No JavaScript unless necessary — static HTML preferred - Allowed JS: share functionality (Web Share API with clipboard fallback). See `CONFIG.md` for share script pattern - Use `content-visibility: auto` for long lists (modern CSS) ## Accessibility (SEO Overlap) - `aria-label` on `<nav>` elements when multiple navs on page - `:focus-visible` for keyboard navigation (already in design system) - Color contrast meets WCAG AA — primary (#000) on surface (#fff) passes - Form inputs must have associated `<label>` elements - Use `<button>` for actions, `<a>` for navigation ## URL Structure - Lowercase, hyphen-separated slugs - Descriptive paths: `/posts/dramatis-personae/` not `/p/123` - Trailing slash consistency — pick one, stick with it - No query parameters for content pages ## Robots & Indexing - `robots.txt` at root - XML sitemap at `/sitemap.xml` - Noindex for utility pages (search results, filters) - Canonical URL on every page to prevent duplicates