Blog

The page outline a non-browser client can follow

Inspect the landmarks, links, labels, and form controls a client receives before JavaScript runs, then test the interactions separately.

author: George Jieh
published: 2026-09-23
reading: 5 min

A contact page can show a clear heading, navigation, and a form while exposing very little of that organization in its HTML. Layout tells a person where to look. Elements and attributes give a parser a different way to identify the content and controls.

Semantic markup is useful when those two descriptions agree. HTML defines nav, for example, as a section containing navigation links to other pages or parts of the page (WHATWG, "The nav Element"). Using it for the site's navigation makes that relationship explicit without requiring a client to infer it from visual placement.

The structure is evidence, not behavior

Consider two contact pages with the same visible copy. One returns a document with a title, a single h1, a main region, a nav with ordinary href links, and a form whose labels, names, method, action, and submit control are present in the HTML. The other returns a thin shell where the form and links are assembled after client code runs.

A person in a browser may be able to use both pages. A static fetch sees a different surface. The first page exposes more of its outline in the response body. The second may require a renderer, later API calls, or site-specific script behavior before the same information appears. That is an observation about the returned HTML, not a verdict on the site's quality.

When reviewing the returned HTML, separate the questions it can answer from those that need a working client:

Does the response contain the main content and controls?
Are navigation relationships represented as ordinary links?
Are forms inspectable without executing JavaScript?
Can a particular client submit, validate, authorize, or complete the task?

Semantic HTML helps most with the first three. It does not answer the fourth.

Forms need names, labels, and fallbacks

A form can be visually obvious yet leave its fields poorly identified in markup. W3C's H44 technique describes the explicit label pattern: the label's for value matches the control's id (W3C WAI, "H44").

For example, this illustrative field gives the user a visible label and publishes its purpose:

<label for="contact-email">Email address</label>
<input id="contact-email" name="email" type="email" autocomplete="email">

The attributes have different jobs. The label identifies the control; name identifies the field in a form submission; autocomplete provides an input-completion hint (WHATWG, "The Autocomplete Attribute"). Check the form's action and method separately. A well-labelled field does not establish that the server will accept a submission.

Button names deserve the same attention. Prefer ordinary visible text that describes the action, and keep it consistent with the accessible name (W3C WAI, "G211"). This is useful markup practice, not a substitute for a complete accessibility or form-behavior test.

What MachineRead observes

MachineRead's Semantic HTML & Agent Navigation check inspects fetched homepage HTML. It parses the static response and evaluates a bounded set of structural signals: heading shape, selected semantic elements, title and meta description, link text and link destinations, image alt attributes, form labels and affordances, and names for selected interactive controls.

The link check is intentionally narrow. Empty destinations, #, and javascript: links are treated as non-crawlable for the heuristic, while ordinary same-document fragment links remain acceptable. The navigation issue appears only when the page has at least eight links and more than a quarter of them are non-crawlable. That threshold keeps one small menu exception from becoming a site-wide conclusion.

For pages with forms, the check looks for static affordances that a fetched document can reveal: explicit non-JavaScript action URLs, supported methods, useful field names, labels, selected autocomplete hints, named submit controls, and at least one non-JavaScript action/method fallback. A passing result means those inspected affordances are present in the returned HTML. It does not test server availability, authorization, validation, spam controls, payment flows, or successful submission.

How to use a finding

Start with the HTML that a plain request receives. If the finding says semantic tags are missing, look for whether the main content is wrapped in landmarks such as main, article, section, header, footer, or nav. Use elements for their normal meaning rather than adding them as decoration.

If the finding points at links, inspect the affected anchors. Replace vague labels such as "click here" with text that names the destination. Replace JavaScript-only navigation with ordinary URLs where that is appropriate for the site. If JavaScript behavior is intentional, decide whether the page also needs a crawlable fallback.

If the finding points at forms, review the markup rather than the browser screenshot. Pair labels with fields, give fields useful names, include an explicit method and action when the form is meant to submit without script, and name the submit control. Then retest the deployed page, because template changes, hydration behavior, and security middleware can change what the fetch receives.

What this check can and cannot establish

The result describes the homepage HTML returned to MachineRead, before scripts run. Use it to locate markup worth fixing, then test the affected navigation or form with the clients the site needs to support. The audit does not establish successful interaction and is not a WCAG conformance assessment.

Works Cited

WHATWG. "The Autocomplete Attribute." HTML Standard, https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#attr-fe-autocomplete. Accessed 9 Sept. 2026.

WHATWG. "The nav Element." HTML Standard, https://html.spec.whatwg.org/multipage/sections.html#the-nav-element. Accessed 9 Sept. 2026.

W3C Web Accessibility Initiative. "G211: Matching the Accessible Name to the Visible Label." WCAG 2.2 Techniques, https://www.w3.org/WAI/WCAG22/Techniques/general/G211.html. Accessed 9 Sept. 2026.

W3C Web Accessibility Initiative. "H44: Using Label Elements to Associate Text Labels with Form Controls." WCAG 2.2 Techniques, https://www.w3.org/WAI/WCAG22/Techniques/html/H44.html. Accessed 9 Sept. 2026.