# Technical SEO playbook
A working checklist for taking a site from "probably fine" to genuinely clean,
written from the things that were actually wrong on real projects rather than
from a list of best practices. Ordered by how much each one moves the needle.
Copy this file into a new project's `docs/`, work down it, and check things
off. Run [`seo-audit`](https://github.com/nurkamol/seo-audit) as you go — it
verifies about two thirds of what follows automatically.
```bash
npx github:nurkamol/seo-audit@v1 https://example.com --html audit.html
```
**Scope, stated once.** Everything here is on-site technical and content
correctness. It makes a site *eligible* to rank. What decides the actual
ordering is off-site — links, a Business Profile, reviews, and content people
want. Anyone promising rankings from a checklist is selling something. See
[Off-site](#off-site-the-part-a-checklist-cannot-do) at the bottom for what
that work actually is.
---
## 1. Crawlability and indexing
The floor. Everything else is wasted if this is wrong.
- [ ] `robots.txt` exists, does not `Disallow: /`, and declares the sitemap
- [ ] A sitemap exists and lists **final URLs only** — no redirects, no
`noindex` pages, no non-HTML files
- [ ] Staging hosts serve `noindex` *and* a `Disallow: /` robots.txt, decided
by hostname so it flips automatically at cutover
- [ ] Production serves neither — check this after any staging work
- [ ] `http://`, `www.` and `https://www.` each reach the canonical host in
**one** hop
- [ ] Trailing slashes are consistent: one form 200s, the other redirects.
Both answering 200 is two URLs for one page
- [ ] Every page has a self-referencing canonical, and only one
- [ ] Canonicals point at URLs that return 200 — not a redirect, not a 404
- [ ] `llms.txt` describes the site for AI assistants ([the convention](https://llmstxt.org))
> **Trap.** A sitemap entry that 301s is not harmless: it tells Google your own
> map of the site is out of date. Regenerate the sitemap from routes, never by
> hand.
## 2. The pages themselves
- [ ] Every page: exactly one `
`, and it is in the content, not the header
- [ ] Heading levels descend one at a time within `` — no `h1` → `h3`
- [ ] Titles are unique, 15–60 characters, and carry the term someone would
actually search plus the location if the business is local
- [ ] Meta descriptions are unique and 70–160 characters — longer gets cut off
mid-sentence in results
- [ ] `lang` on ``, and a viewport meta
- [ ] No page that matters is under ~300 words. A 120-word page with a
competitive title cannot rank, and no amount of technical work changes
that
> **Trap.** Don't pad a title to hit a character count. "48 characters" is not
> a problem; a title that omits what the page is about is.
## 3. Internal linking
The highest-value item most sites are missing entirely, and the one no
single-page grader can see.
- [ ] Pages link to each other **from inside the content**, not only from the
nav and footer
- [ ] Long-form articles link to the product, service or page they discuss
- [ ] Related pages cross-link where the copy already names the other thing —
anchor existing wording rather than writing "click here"
- [ ] No orphans: every page in the sitemap is linked from somewhere
- [ ] No page linked from the site is missing from the sitemap
- [ ] Every internal link resolves — run a full-site 404 sweep, not a spot check
> **How to check quickly.** If every page reports the same number of internal
> links, they are all nav and footer, and the content links to nothing.
## 4. Multilingual
Skip if the site is one language. If it isn't, this is where the silent
breakages live.
- [ ] `hreflang` on every page, **reciprocal** — if A points at B, B must point
back, or Google ignores the pair
- [ ] `x-default` points at the language a stranger should land on
- [ ] Slugs may differ per language — a Russian article should have a Russian
URL
- [ ] **The language switcher uses the page's real translation, not a path
swap.** This is the single most expensive bug on this list
> **Trap, and a true story.** A site swapped the `/ru` prefix on the current
> path to build its language switcher. That works for mirrored pages and 404s
> for every article whose translation has its own slug. `hreflang` was correct,
> so Google knew the right pairing while every human visitor hit a dead page.
> Three commercial SEO tools audited that site the same morning and none saw
> it, because the link is only broken on pages they never opened.
## 5. Images
- [ ] Every `
` has an `alt` attribute — `alt=""` for decoration, a real
description otherwise. The attribute must exist either way
- [ ] The `alt` actually describes *this* picture. `alt="DSC_0042.jpg"` and
`alt="image"` pass a presence check and help nobody, and a whole gallery
sharing one description is a template nobody filled in
- [ ] `alt` stays under ~125 characters. It is read out in one breath, with no
way to skim or pause — a longer description belongs in the page text,
where sighted readers get it too
- [ ] Every `
` has `width` and `height`, so the browser reserves the box
and the page doesn't reflow as images arrive
- [ ] **`img { height: auto }` is in the CSS.** With dimensions set and no
`height: auto`, the browser treats the height attribute as a literal
pixel height and images render stretched
- [ ] `srcset` + `sizes` so a phone doesn't download the desktop file. Typical
saving: 60 KB → 12 KB per card image
- [ ] Modern formats (WebP/AVIF) for on-page images
- [ ] `loading="lazy"` below the fold, and **never** on the LCP image
- [ ] The LCP image is preloaded in `` with `fetchpriority="high"`
- [ ] **A preload must carry the same candidates as the element's `srcset`**
(`imagesrcset` / `imagesizes`), or the browser fetches the full-size
original *and then* the variant it actually wanted
> **On decorative images.** If the container is `aria-hidden`, a screen reader
> never reaches the image whatever its alt says. So an empty alt there costs
> nothing — and gains nothing. A real description costs nothing either and
> makes the photography eligible for image search. Describe the picture, not
> the page title.
## 6. Social previews
- [ ] Every page has `og:title`, `og:description` and `og:image`
- [ ] `og:image` is **1200×630** and **JPEG or PNG** — LinkedIn does not render
WebP and WhatsApp is unreliable with it
- [ ] `og:image:width`, `height` and `type` are declared on every page, not
just the default
- [ ] Each page previews with its own image, not one generic card
- [ ] `twitter:card` is `summary_large_image`
- [ ] Generate the crops at build time from the page's own photo, and fail the
build if a page references one that wasn't produced
> Worth doing: composite the logo onto the generated crop over a soft gradient.
> One image then works over both a dark photograph and a bright one, and a
> shared link is recognisable before anyone reads the title.
## 7. Structured data
- [ ] `Organization` or `LocalBusiness` + `Person` + `WebSite`, emitted once,
on the home page. A `@graph` is valid and Google reads it
- [ ] `LocalBusiness` carries name, URL, telephone, email, address, areaServed,
a real photo, and `sameAs` for every social profile
- [ ] `hasOfferCatalog` lists the services, each linking to its own page
- [ ] `Service` on service pages, `BreadcrumbList` where there's a hierarchy
- [ ] `FAQPage` on a Q&A page — with the markup **stripped** from the answer
text, so Google isn't shown `[link](/path/)`
- [ ] `BlogPosting` on articles with `datePublished` **and** `dateModified`
- [ ] It validates: [Rich Results Test](https://search.google.com/test/rich-results)
and [validator.schema.org](https://validator.schema.org)
> **Do not** add `aggregateRating` built from testimonials hosted on your own
> site. Google disallows self-serving review markup and it risks a manual
> action. Reviews belong on the Business Profile.
>
> **Do not** invent `geo`, `openingHours` or `priceRange` because a validator
> wants them. Wrong data in front of Google is worse than absent data.
## 8. Performance
Measure it, don't estimate it — [PageSpeed Insights](https://pagespeed.web.dev)
and [WebPageTest](https://webpagetest.org) run real browsers, and WebPageTest
lets you pick a location your customers actually live in.
- [ ] Fonts are **self-hosted**, subsetted to the scripts the site uses
- [ ] Only the faces that set first paint are preloaded, in the subset that
page needs — a Cyrillic page has no use for the Latin cut
- [ ] No render-blocking third-party stylesheet
- [ ] Third-party JavaScript is justified per script. Analytics that nobody
reads is pure cost — a single tag manager is routinely 160 KB
- [ ] Consent Mode or equivalent: storage denied until the visitor accepts
- [ ] CLS under 0.1 — mostly solved by image dimensions
- [ ] Cache headers on hashed assets
> **Trap.** Self-hosting fonts removes a render-blocking request and a privacy
> problem. It does **not** make the files smaller. If the total is still 250 KB
> across six faces, subset them or drop the ones barely used.
## 9. Trust and credibility (E-E-A-T)
The half that isn't code, and the half most sites skip.
- [ ] Articles show an author and a visible date
- [ ] The author has a real bio somewhere, with credentials, and the article
links to it
- [ ] Testimonials are attributed — a first name and context beats "★★★★★"
- [ ] Contact details, a physical presence if there is one, and clear legal
pages
- [ ] Legal pages have real titles and descriptions, not "Disclaimer"
- [ ] Nothing overstates what the business can do. For anything health-adjacent
this is a ranking factor, not just ethics
## 10. Local business
- [ ] **Google Business Profile claimed and complete.** For a local service
this outweighs the entire website in map results
- [ ] Name, address and phone identical on the site, the Profile, and every
directory
- [ ] A `tel:` link and the locality visible on the site itself
- [ ] Reviews requested from real clients, on the Profile — never on your own
site marked up as ratings
---
## Off-site: the part a checklist cannot do
Being honest about this is the difference between a useful engagement and an
expensive one.
| Lever | Reality |
|---|---|
| Backlinks | The strongest signal, and the hardest. Directories, partners, guest articles, interviews. Zero referring domains means zero authority, however clean the HTML |
| Business Profile + reviews | For local search, the single biggest lever |
| Content depth | Publishing consistently, about things people search for |
| Time | A new domain does not rank quickly, whatever anyone says |
---
## Working process
The discipline that keeps this from rotting after week one.
1. **Baseline before you start.**
```bash
npx github:nurkamol/seo-audit@v1 https://example.com --json seo-baseline.json
```
Commit `seo-baseline.json`.
2. **Configure what the site lives with.** Every site has findings that are
true and deliberate — a contact page is meant to be short, a privacy policy
has no business carrying editorial links. Put them in
`seo-audit.config.json` (see below) so the report stays readable.
3. **Gate CI on regressions, not on the backlog.**
```yaml
- uses: nurkamol/seo-audit@v1
with:
url: https://example.com
baseline: seo-baseline.json
fail-on: new
comment: true
```
4. **Wait for the edge before auditing.** A CDN serves a fresh deploy unevenly
for a minute or two — one POP has the new page, another the old, and 404s on
new assets get cached briefly. Auditing during that window produces a
snapshot that is wrong in a way nobody can reproduce. Use `--settle 60`, or
poll until several consecutive requests agree.
5. **Re-run the external tools after real changes**, not before. They cache
reports, and their categories differ from Google's: several count `alt=""`
as missing, and one will insist a site has no CSS media queries while
another scores its mobile experience 100.
---
## Starter config
`seo-audit.config.json` in the project root:
```json
{
"limit": 200,
"failOn": "error",
"limits": { "thinWords": 300 },
"psi": ["/", "/blog/**"],
"ignore": [
{ "id": "thin-content", "urls": ["/contact/", "/thanks/", "**/legal/**"] },
{ "id": "no-editorial-links", "urls": ["**/privacy-policy/", "**/terms-of-use/", "**/cookie-policy/"] }
],
"expect": [
{ "urls": ["/"], "types": ["Organization", "WebSite"] },
{ "urls": ["/blog/*/"], "types": ["BlogPosting"] },
{ "urls": ["/faq/"], "types": ["FAQPage"] }
]
}
```
Every `ignore` entry should be defensible out loud. If you can't say why a
finding is acceptable, fix it instead of hiding it.
---
## Handing this to an AI agent
Drop this file in `docs/` and give the agent something like:
> Read `docs/SEO-PLAYBOOK.md`. Run
> `npx github:nurkamol/seo-audit@v1 --html audit.html --json audit.json`
> against this project, then work through the playbook section by section.
> For each item: check whether it is true of this codebase, fix it if not, and
> tell me which items you could not verify or that need a decision from me.
> Do not invent business facts — addresses, opening hours, prices, credentials.
> Verify each fix against the built output before moving on, and wait for the
> CDN to settle before auditing a fresh deploy.
The last two sentences matter more than the rest. Most of the damage an
enthusiastic pass does is inventing structured data that isn't true, and
declaring success against a stale cache.