Summary

Fixed every broken link flagged by HTML Proofer and repaired the npm run proof command itself, so the link check can run again and finishes with zero failures.

Related issue

Closes #3187

Problem statement

The site's link checker hasn't been able to start for a while: the proof scripts in package.json still use html-proofer 3.x flag syntax (--enforce-https=false, --only_4xx), which the pinned html-proofer 5.0.0 gem rejects before checking a single page. With the checker offline, links that moved or disappeared piled up unnoticed — exactly the situation this issue predicted. Running a corrected check today surfaces 24 failures: 3 in-page anchors that lead nowhere and 21 hits on external pages that moved or were taken down.

Solution

Two parts — make the checker work, then fix what it finds:

1. Restore the checker. Updated both proof scripts to html-proofer 5 syntax (--no-enforce-https, --allow-missing-href, --only-4xx) and bumped the gem from 5.0.0 to 5.2.2. The version bump matters beyond the flags: in 5.0.0 the /regex/ patterns passed to --ignore-files are silently treated as literal strings, so the intended exclusion of 2017–2021 archive posts never applied. 5.2.2 parses them as real regular expressions again, which keeps old blog posts out of the scan as the script always intended.

2. Fix the 24 failures. All in-page anchor bugs are fixed at their source, and every dead external link now points to a live, verified destination (details below).

Major changes

In-page anchors

• The Developers page navigation pointed to #contributing-to-the-code-base, but the heading's real ID is #contributing-to-the-codebase. Fixed the nav link.
• Component pages without a type value rendered their "Using the…" heading ID with a stray hyphen at the end (for example #using-the-default-banner-). The template now only appends the type when one exists. This cleans up the malformed IDs on four variant pages; nothing linked to the old malformed IDs.
• The default banner's usability text linked to #using-the-banner-component, an anchor that only exists on the main Banner page. It now points to the matching section on its own page, #using-the-default-banner.

Moved or removed external pages

• Technology Transformation Services (3 pages): GSA removed the old organization page during its site reorganization. Links now point to https://tts.gsa.gov/, the official TTS home.
• GSA accessibility aids (2 links): that page's content — the list of plug-ins and file viewers — now lives in a section of GSA's accessibility statement. Links updated to https://www.gsa.gov/website-information/accessibility-statement.
• Plain language: GSA's plain-language page is gone and PlainLanguage.gov now redirects to Digital.gov's plain language guide. Link updated to https://digital.gov/guides/plain-language.
• Small business events and contacts: GSA split the old OSDBU events page into separate training-and-events and get-help pages. The link now points to https://www.gsa.gov/small-business, the hub that links both halves of the original content.
• "Using a service ecosystem to quickly grasp complexity": the Service Design Network removed its community-knowledge section in a redesign. The article (Jesse Grimes, Touchpoint Vol. 10 No. 2) lives on at the author's own site, which states it was originally published in Touchpoint. Link and attribution updated to kolmiot.com. (SDN's official Medium copy exists too, but Medium blocks automated link checks, so it would keep failing the proofer.)
• SAMHSA trauma publication (SMA14-4884): SAMHSA withdrew this 2014 publication — the PDF now 404s on library.samhsa.gov and its catalog page is gone, with no live replacement on any SAMHSA site. Since this is a dated research citation ("Retrieved on July 21, 2022"), it now cites the Internet Archive snapshot of the exact URL originally referenced.
• U.S. Data Federation showcase entry: removed. The project ended and federation.data.gov now redirects to a 404; only a historical-record page remains on resources.data.gov, so there's no longer a USWDS-built site to showcase.

Testing and review

• npm run proof — HTML-Proofer finished successfully, 0 failures. (Before this change the command exits immediately with an option-parsing error; with only the flags corrected it reports the 24 failures listed above.)
• bundle exec rspec — 10 examples, 0 failures.
• npm run lint — passes.
• Every replacement URL was verified to return HTTP 200 with redirects followed, using a browser user agent.

A good review pass: spot-check the replacement URLs above, and confirm you're comfortable with the three judgment calls — the archive.org citation, the kolmiot.com republication, and removing the Data Federation showcase entry.

Dependency updates