Files
Nick Vigilante b2474d19d7 feat: own the docs accessibility checks the axe Linter doesn't run on Markdown (#30905)
## Merge order

This PR was stacked on #30879, which has merged. It now targets `main`
and has no remaining dependency.

## Summary

The axe Linter checks only one rule in Markdown, `heading-order`, and
markdownlint `MD001` already covers it for Markdown headings. This PR
adds owned checks for the raw HTML in docs Markdown that neither tool
sees, so the coverage stays when the licence ends.

- `Coder.HeadingOrder` (Vale) flags heading-level skips and counts raw
`<hN>` headings, such as the `<h3>` headings `scripts/apidocgen` emits,
which `MD001` ignores.
- `Coder.EmptyHeading` (Vale) flags headings with no text, in Markdown
and raw HTML.
- `Coder.LinkName` (Vale) flags links with no text: `[](url)`, links
whose only content is an image with empty alt text, and empty `<a
href>`.
- `docshtmlcheck` now rejects `aria-*`, `role`, `tabindex`, and `lang`
attributes, and `iframe`, `object`, `area`, `form`, `input`, `select`,
`textarea`, `button`, and `meta` elements. No docs page uses any of
them, so the 32 axe HTML rules that check them have nothing to check,
and this keeps it that way.
- The style guide's decorative-image example changes from
`![](decorative.png)`, which `MD045` rejects, to `<img src="…" alt="">`.
No docs page used the old form.
- The style guide's checks table gains a row per new check, and the
coverage counts move the descriptive-link-text section from planned to
tool-checked (22 of 90 rules tool-checked, up from 21 on `main`).

## Design

All three Vale rules are `script` rules on `raw` scope, because heading
levels, empty headings, and links with no text only show up in the raw
source. Raw scope also reaches YAML front matter, fenced code, HTML
comments, and inline code, so the scripts skip those themselves. Fence
tracking matches the opening marker's character and length, so a
four-backtick fence holding a three-backtick one stays closed correctly.
The patterns use only capture groups that always participate, because
Tengo's `text.re_find` panics on a group that didn't match.

`Coder.HeadingOrder` is built to agree with `MD001` without reporting
the same skip twice. It tracks the previous heading of any kind and the
previous Markdown heading. It stays quiet on a Markdown heading that
`MD001` already reports (a skip measured against the previous Markdown
heading) and reports the skips `MD001` can't see: a raw HTML heading
that skips, and a Markdown heading that skips only because a raw HTML
heading sits before it. On a probe file covering each case, the two
tools reported disjoint lines. The one remaining divergence is by
design: after `## A`, `<h3>B</h3>`, `#### C`, `MD001` reports C (it sees
H2 to H4) while this rule sees a clean H2, H3, H4 sequence and stays
quiet, so the author still gets exactly one finding.

The `docshtmlcheck` guard is a separate `guard.go` that runs on each
start tag the existing tokenizer already walks. The elements stay in
`allowedElements`, so authors get a message explaining why the element
doesn't belong rather than the generic unknown-element one, and a closed
`<button>` still balances. Guard findings get their own kinds
(`disallowed-element`, `disallowed-attribute`) and their own summary
footer. I included `form` alongside the form controls the issue lists,
since a form with no controls has no use either.

Known gaps, documented in each rule's header and none hit by the current
corpus: setext headings, headings inside block quotes or list items, raw
HTML headings or links split across lines, reference-style links, and
inline code delimited by more than one backtick. There is no Vale rule
test harness in the repository, so the hit and non-hit probe files used
below live outside the tree.

## QA

I ran each Vale rule against a probe file with hits and non-hits, with
the repository `.vale.ini` and the pinned Vale 3.7.1.

- `Coder.HeadingOrder`: reported the raw `<h4>` after an `##` and the
`###` that follows a raw `<h1>` after a `###`. It stayed quiet on the
two skips `MD001` reports, on `#` lines in front matter, fenced code,
and an HTML comment, and on a clean sequence. markdownlint on the same
file reported only the two `MD001` lines, so no line got both.
- `Coder.EmptyHeading`: reported `##`, `### ###`, `<h2></h2>`,
`<h3>&nbsp;</h3>`, and `<h4> <br/> </h4>`. It stayed quiet on text
headings, seven `#` marks, an empty `<h2>` in inline code, and lone `#`
lines in front matter, fences, and comments.
- `Coder.LinkName`: reported all 7 hit cases (empty, whitespace, `![]()`
inside a link, raw empty-alt `<img>` inside a link, empty `<a href>`,
`<a href>` around an empty-alt image, `<a href>` holding only `&nbsp;`).
It stayed quiet on all 9 non-hit cases, including a bare decorative
image, `<a id>` anchors, inline code, comments, and fenced code.

Findings on the current corpus (`docs/`, excluding the exempt style
guide): `Coder.HeadingOrder` 0, `Coder.EmptyHeading` 0, `Coder.LinkName`
0, `docshtmlcheck` guard 0. The other Vale findings are unchanged from
before the PR. No corpus pages changed.

## Testing

- `go test ./scripts/docshtmlcheck/ ./scripts/styleclaims/`: 140 passed.
The guard tests were written first and failed before `guard.go` existed.
They cover each element, each attribute (including case-insensitive
names and attributes wrapped across lines), lookalike names such as
`data-role`, code and comment exclusion, the reported line and message,
and the `run` exit code and footer.
- `make lint/docs-html`: clean.
- `make lint/style-claims`: clean, so the checks table, the coverage
counts, and the annotations agree with `.vale.ini` and the rule files.
- `make lint/emdash`: clean.
- `pnpm check-docs` (markdownlint and table formatting): 0 errors across
515 files.
- Vale 3.7.1 over `docs/` with `--no-exit`, run directly rather than
through `make lint/prose` because the worktree's mise config isn't
trusted: no findings from the new rules.

## Upstream

Not applicable. These checks are specific to the Coder docs corpus and
its style guide, so there's nothing to send to Vale, markdownlint, or
goldmark.

## Linear

https://linear.app/codercom/issue/DOCS-1318

---

🤖 Built with AI assistance.
2026-11-18 12:24:23 -05:00
..

docshtmlcheck

docshtmlcheck fails CI when Markdown under docs/ contains invalid inline HTML that the documentation site's renderer silently drops or mangles, a table header cell with no text, or an element or attribute that docs pages don't use. It runs as make lint/docs-html (part of make lint).

What it catches

  • Swallowed angle-bracket placeholders. An unwrapped placeholder such as <region> or <server>__ is parsed as an unknown HTML tag and stripped from the rendered page, so readers see broken text. Wrap placeholders in backticks so they render as inline code (see contributing/documentation.md). This also covers CLI --help strings and Swagger annotations, whose text is generated into docs/reference/**.
  • Void-element end tags such as </br>. Void elements like <br>, <img>, and <hr> have no end tag.
  • Capitalized or unregistered component tags such as <Image> or <Table>. The docs renderer reads a capitalized tag as a component reference and drops it unless the component is registered (only the lowercase <children> directive is). Any name outside the standard HTML5 element set is reported the same way.
  • Unclosed container tags, for example a <div class="tabs"> that is never closed and leaks its wrapper over the rest of the page.
  • Empty table header cells (empty-table-header). Screen readers announce a header cell with no text as an unnamed column or row. The check covers the header row of Markdown pipe tables and every <th> in raw HTML tables, after decoding entities and trimming whitespace, so <th>&nbsp;</th>, | &nbsp; |, and <th><br></th> are reported. An entity inside a code span is literal text, so `&nbsp;` counts. Markdown between the HTML blocks of a <th> counts as its text, and so do an image's alt text, an autolink, and a code block. Each finding names the table by its first non-empty header. For the top-left corner of a matrix, name what the row headers hold, such as Permission.
  • Elements and attributes docs pages don't use (disallowed-element, disallowed-attribute). The check rejects aria-*, role, tabindex, and lang attributes, and <iframe>, <object>, <area>, <form>, <input>, <select>, <textarea>, <button>, and <meta> elements. Each one brings accessibility requirements of its own, such as an accessible name, a valid role, a sensible focus order, or a valid language tag, that no docs check verifies. No docs page uses any of them, so keeping them out keeps those requirements out too. Write the content in Markdown, link to embedded content instead of framing it, and use bold text for a UI label instead of a <button>.

How it works

Each file is parsed with goldmark and only raw-HTML nodes are inspected, so angle brackets inside fenced code blocks, inline code spans, HTML comments, and <https://…> / <user@host> autolinks are ignored. Each raw-HTML node is tokenized as a whole with golang.org/x/net/html, so a tag whose attributes wrap across lines is not torn in half. A tag whose raw name is capitalized is reported as a component reference; otherwise any name outside the standard HTML5 element set (plus the intentional <children> renderer component, which is still balance-checked) is reported. Inline SVG and MathML are intentionally not in the allowed set (no docs page uses them); add the element to allowedElements in main.go if that changes. A finding on a generated page under docs/reference/** also prints a note pointing at the generator source, since edits to the generated file do not persist.

The table check parses the same file a second time with goldmark's table extension. It reads the header row of each pipe table from the parsed cells, and follows <table> and <th> through the raw-HTML nodes, so a table split across several HTML blocks is checked as one and Markdown between its blocks counts toward the open cell.

Limitations

A few gaps are accepted because no docs page hits them today:

  • A placeholder whose name is itself a real HTML element (<input>, <time>) is indistinguishable from intended markup and passes. Such placeholders almost always live in fenced code blocks, which are ignored.
  • The interior of a raw-text element (<script>, <style>) is a single opaque token to the HTML tokenizer, so a tag nested inside one is not scanned. An unclosed <script>/<style> is still caught.
  • A table nested inside a <th> doesn't count toward that cell's text, so the outer header cell is reported as empty even when the nested table has text.

Usage

$ go run ./scripts/docshtmlcheck        # scans docs/
$ go run ./scripts/docshtmlcheck path/to/file.md path/to/dir

Allowlist

allowedUnknownTags in main.go is a deliberately narrow, per-file escape hatch for placeholders whose source is outside this repository (so they cannot be fixed by a source edit here). It is currently empty.

The escape hatch is self-clearing: if an allowlisted tag no longer appears in its file (for example once the upstream fix and dependency bump land and the generated page no longer emits the bare placeholders), the linter reports a stale-allowlist-entry and fails until the dead entry is removed, so a suppression can never silently mask a later regression of the same tag.