toolkit

Scenario · Content and search

Turn a selected page into a work plan

“The strategist picked this page for the month — what actually needs to change on it?”

Once a strategist has already picked the one page worth working on this month, restating everything already known about it in another audit just hands them the same page a second time. This turns that single selected page into an actual change list — the specific fix, the evidence behind it, the priority, and the number that will prove it worked — while explicitly calling out what's already fine and should be left alone, so an editor gets something to execute rather than something to re-read.

What to ask for

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.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.Internal link graphInternal link-graph audit — given a site's URL universe, fetches each page, extracts the internal links, and builds a directed graph of how the site links to itself, then grades the signals rankings depend on: ORPHAN pages linked from nowhere, pages unreachable from the home page, pages buried too many clicks deep, thin single-inlink pages, generic anchor text, and exact-match over-optimization.Content qualityContent-quality audit — reads a page's visible text and grades whether the copy itself is any good: readability (Flesch–Kincaid grade and reading ease), thin content by word count, H1/title duplication, and leftover placeholder or lorem-ipsum text.Spelling checkSite-wide spelling sweep — fetches a page (or every URL in a list), extracts the visible text, and flags suspected misspellings with a hunspell dictionary (nspell + dictionary-en).Content freshnessContent-freshness audit — works out how old a page's content is from every freshness signal it can see: schema datePublished/dateModified, time elements, the Last-Modified header, and visible "last updated" dates.Performance (Core Web Vitals)Core Web Vitals and performance scan for a live page.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.Layout / front-end QAFront-end / layout QA for a live page — measures the rendered DOM across device presets and flags objective layout defects: horizontal overflow, tap targets too small, text below the legible floor, skipped heading levels, DOM bloat, interactive elements whose contrast passes at rest but fails on hover or focus, a mobile nav toggle that reveals nothing, and viewport meta defects (missing or blocking zoom).ScreenshotsCapture multi-device screenshots of any URL from the command line — one PNG per device preset (iPhone → Desktop 4K), headless, on a Playwright core.WordPress inspectorRead-only WordPress site inspector — fetches a URL and reports what the site is running before you touch it: whether it is WordPress at all, the WP and PHP versions, web server and managed host, active theme and child theme, the page builder (Divi 4 vs 5, Elementor, Beaver Builder, WPBakery, Bricks, Oxygen, Gutenberg), the plugins visible from outside, the caching and CDN layer, and externally-visible security notes — into a DETECTED / LIKELY / NOT WORDPRESS verdict plus an HTML report.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.SEMrush researchOptional integration — SEO-research client for the SEMrush Analytics API.

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 ↗

The toolkit already grades every individual page signal on its own. What it hasn’t had is the step after that: a strategist names one page, and the handoff back needs to be a work plan with a proposed change and a priority on every row — not another audit restating what’s already known.

  1. Confirm exactly one page, already selected. If the real ask is “which page should we work on this month,” that’s the selection job, not this one — this recipe assumes the URL is settled.
  2. Grade on-page fundamentals and structured data. Title, meta, canonical, headings, and social/schema markup, against zero. This is the baseline every recommendation below either confirms is already clean or proposes changing.
  3. Pull link and image evidence. Broken links and images on the page itself, and — where a URL universe already exists for the site — the internal link graph. An under-linked or orphaned page is where the recommendation “add internal links from these pages” writes itself.
  4. Grade content on three separate axes. Readability, spelling, and freshness relative to a normal refresh window. Keep them separate — a page can be readable and stale, or freshly edited and hard to read, and a blended score would hide which one is actually the problem.
  5. Grade technical and UX signals, and capture the page while at it. Performance, accessibility, layout, and — where the stack is WordPress — plugin/theme health. Screenshot it across devices in the same pass, since the before-state is needed again in step 9 regardless.
  6. Add keyword and competitive context where it’s configured. A content brief for the target term if one doesn’t already exist, and keyword-gap data against competitors through the SEMrush client. Both are optional inputs — where the account isn’t configured, or a competitor-comparison tool isn’t available, the search-intent read is labelled “Not verified — data unavailable” rather than blocked or guessed at.
  7. Write the output as a change list, not a findings list. Each row: the issue, the exact change — copy, tag, or structure — where evidence supports a specific one, the evidence it rests on, the impact, the effort, a P1/P2/P3, and the post-change KPI that will tell you it worked (position, CTR, clicks, or conversions for that page). A row with no proposed change is a finding, not a work-plan item, and doesn’t belong in this document.
  8. [manual] Add a “what not to change” section. Every check that already passes gets named as passing and left alone. The point of running the full check set first is exactly so an editor doesn’t rewrite something that was never broken.
  9. Record the baseline before anything is edited. The screenshot capture from step 5, plus current position and impressions for the target term. This is the same before-state every recipe here relies on, and it’s the only way “did this work” has an answer once the changes are live.
  10. [manual] Make the approved changes, then rerun steps 2, 4 and 5 against the published page to confirm the work landed and record the result.

Reuses tool JSON outputs and report-kit rather than duplicating each scanner; a page that already satisfies a check is explicitly retained rather than rewritten.

A work plan, not another audit

The difference between this and grading the page in isolation is that every row here carries a proposed change, evidence, and a priority. An audit that stops at “here’s what’s wrong” hands the strategist the same page a second time; a work plan hands them something to execute.

What this does not cover

Which page to pick. Selecting the month's priority URL from Search Console data is a separate job with its own ranking logic — this recipe starts only once a URL has already been chosen, for one or two pages at a time. It also never writes to the CMS or invents anything: a source with no data available is labelled "Not verified — data unavailable," never filled in with a guess, and every change here ships through the normal manual publish step like any other content edit.

← All scenarios