toolkit

Scenario · Content and search

Put this document on the site

“Can you put our new patient intake form up as a PDF?”

Putting a document on the site looks like a simple upload, but the two ways it actually goes wrong are invisible until later: the file itself might contain something it shouldn't — an old patient's name, last year's pricing — and a replaced document usually leaves the old version still live and still linked from somewhere. This checks whether the file is already referenced elsewhere on the site so the old copy actually gets cleaned up, and verifies the new link works after publishing; reading what's actually inside the document is still a job for a person, every time.

What to ask for

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.Site-wide content searchSite-wide content scout — searches every page of a site (or one page) for literal phrases or labelled regex rules and reports every occurrence with its surrounding sentence, so a copy change can be scoped before anything is edited.Sitemap & robotsRead-only sitemap & robots map — fetches a site's robots.txt and every sitemap it declares (or probes the common locations), follows sitemap indexes down to their children, collects every URL, and reports what is declared, what robots.txt blocks, and what is oversized, cross-host or insecure, plus a crawl-over-crawl diff.Before/after checkBefore/after verification for a change to a live page — the safety net for the small edit that doesn't justify a staging round-trip.

See it work

A real run of Link & image checker:

FAIL — 1 page(s) on toolkit-tests.pages.dev · 1 unique broken target(s)
      ✗ link: 404: https://toolkit-tests.pages.dev/links/does-not-exist-404.html  (1×)
      4 links · 0 images · checked 4+0
      [error] 1 broken link(s) — 404: https://toolkit-tests.pages.dev/links/does-n…

  playbook: local fallback

  report: ./out/link-and-image-checker-link-and-image-checker.html
  text:   ./out/link-and-image-checker-link-and-image-checker.txt

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

Uploading a file is the easy part. The problems are that a PDF is a dead end for a visitor who needed a web page, and that a replaced document usually leaves the old one live at its old URL, still linked from somewhere and still being downloaded.

  1. Open the document and read it. Confirm it is the right version, and that it contains nothing it should not — old patient names in a filled-in example, a previous year’s pricing, internal comments. Nothing downstream will catch this.
  2. Ask whether it should be a page instead. An intake form, a price list or a post-op instruction sheet as a PDF cannot be read comfortably on a phone, is largely invisible to search, and is harder for a screen reader. If the content is the point, the answer is a page; if the point is that it gets printed and signed, a PDF is right.
  3. Check whether it is replacing something. Search the site for the existing document’s filename and link text, with the raw pass on — links to files live in buttons and hrefs, not visible copy. Missing this is how two versions of an intake form end up live at once.
  4. [manual] Upload with a clean, dated filename and link to it. Something like patient-intake-form-2026.pdf, not Scan_0142_final_v3.pdf — the filename is the URL, it is permanent, and it is what a visitor sees when they download it. Link with text that says what it is and that it is a PDF. Publish and purge.
  5. [manual] Deal with the old version. Remove it or redirect its URL to the new one, and update every reference found in step 3. An old PDF left in place is still indexed and still downloaded, and it will be the one someone brings to an appointment.
  6. Verify. Link check on the pages carrying the link — a mistyped upload path returns a 404 that looks like a working button. Re-run the reference search for the old filename: zero hits. Before/after check on the pages touched. Confirm the file is reachable at its URL by fetching it.
  7. Check whether it should be in the sitemap. A document meant to be found in search belongs there; a form only reachable from a page it is linked on does not need to be.

The superseded copy is the failure

Replacing a document is treated as an upload, so the old file keeps its URL, keeps its inbound links, and keeps being served. Steps 3 and 5 are the whole reason this has a procedure — everything else is genuinely as simple as it looks.

What this does not cover

Inside the document. Nothing here reads a PDF: its text is not spell-checked, its accessibility is not audited, and whether it contains a patient's details left in from a previous version is not something any check will notice. That last one is the real risk with practice documents, and it needs a human opening the file before it is published.

← All scenarios