toolkit

Scenario · Content and search

We need a new page

“We need a page for [a treatment, a location, a new service].”

A new page is the one request where every check can run before anything is broken — there's no regression to hunt for yet, only a standard to meet before the page ever goes live. This briefs the page against its actual target search term before it's written, then grades the finished page against everything that makes it findable and usable, catching the expensive mistake of a page that gets built, reviewed, and only then discovered to be targeting the wrong term or duplicating a page that already exists.

What to ask for

Content briefContent brief generator — turns a keyword into a brief a writer can execute without further research: search intent and audience, a recommended title / meta description / H1, an H2–H3 outline, entities and questions to cover, internal-link anchors, and a word-count target.On-page SEOOn-page SEO scan — reads a page's delivered HTML and checks the head, meta and heading signals search engines use: title presence and length, meta description, rel=canonical, meta robots (noindex), Open Graph tags, viewport, html lang, and exactly one H1, plus a structured-data summary.Structured data (schema)Structured-data audit — checks a page's JSON-LD against a per-type rubric: valid JSON, a schema.org context, and the required and recommended properties that gate rich results for Organization, WebSite, Article, Product, LocalBusiness, BreadcrumbList, FAQPage, Event, Recipe and more.Accessibility (a11y)Accessibility scan for a live page — runs axe-core (Deque) across device presets and scores the page against WCAG, returning an absolute PASS / REVIEW / FAIL verdict plus a self-contained HTML report grouped by impact.Performance (Core Web Vitals)Core Web Vitals and performance scan for a live page.Link & image checkerOn-page link & image checker — extracts every link and image a page declares, fetches each to its status code, and reports the dead ones (4xx/5xx broken links and broken images) plus the link-quality issues search engines and screen readers care about: non-descriptive anchor text, image-only links with no accessible text, malformed links, insecure external links, new-tab links missing rel=noopener, and excessive link counts.ScreenshotsCapture multi-device screenshots of any URL from the command line — one PNG per device preset (iPhone → Desktop 4K), headless, on a Playwright core.

See it work

A real run of On-page SEO:

FAIL — 1 page(s) on toolkit-tests.pages.dev
      [error] missing <title>
      [warn] missing meta description
      [error] no <h1> on the page
      [warn] no rel=canonical link
      [warn] no viewport meta (mobile rendering)
      [warn] no lang attribute on <html>
      [warn] no Open Graph tags — shared links get a guessed title/description and no image
      [info] no <link rel="icon"> declared (a root /favicon.ico may still resolve; declare one for a modern SVG/PNG icon)
      [info] no apple-touch-icon — iOS home-screen bookmarks fall back to a page screenshot
      [info] no web app manifest (<link rel="manifest">) — needed for an installable PWA / richer mobile metadata
      [info] no theme-color meta — mobile browsers use it to tint the address bar
      [info] no structured data (see structured-data-schema)

  playbook: local fallback

  report: ./out/on-page-seo-on-page-seo.html
  text:   ./out/on-page-seo-on-page-seo.txt

The captured report, exactly as a run hands it to a client —open the full report ↗

A new page is the one request where the checks are worth running before it goes live rather than after, because nothing is broken yet — there is no regression to find, only a standard to meet.

  1. Brief the page before it is written. Given the target keyword, the brief produces the search intent, a recommended title and meta description, an H2–H3 outline, the entities and questions to cover, and a word-count target. A page written without one is a page that gets rewritten.
  2. [manual] Build the page in the CMS. Following the brief, using an existing template rather than a fresh layout wherever possible. This is the work, and it is the step that decides whether any of the checks below have anything to complain about.
  3. Grade it before launch, on the staging or unpublished URL if there is one. On-page SEO for the title, meta description, canonical, single H1 and Open Graph tags; structured data for the schema type the page needs; accessibility; performance. Fix what they return now — every one of these is cheaper to fix before the page has links pointing at it.
  4. Check every link and image on it. New pages ship with placeholder hrefs and images that were never uploaded more often than any other kind of page.
  5. Capture it across devices. A new layout is the most likely thing to break on mobile, and a screenshot set is what makes that obvious without opening a phone.
  6. [manual] Wire it into the site. Add it to the navigation where it belongs, link to it from the relevant parent or service page, and confirm it appears in the sitemap. A page that exists but is unreachable is the most common way a new page quietly fails.
  7. Re-run the on-page grade against the live URL once it is published, so the record is of the page as visitors get it rather than as staging served it.

Why the brief is step one and not optional

The most expensive version of this request is the one where the page is built, reviewed, and then found to be targeting a phrase nobody searches or duplicating a page that already exists. That is a decision made before any code, and the brief is where it gets made cheaply.

What this does not cover

Writing the page and deciding it should exist. It briefs the page, then grades the built page against everything that makes a page findable and usable; it does not judge whether the practice should offer this service or whether the copy is medically sound. It also cannot know the page is in the navigation or the sitemap unless you check — a live page nobody links to is a page nobody visits, and that is not a defect any single-page check reports.

← All scenarios