Repository navigation
feat: own the docs accessibility checks the axe Linter doesn't run on Markdown - #30905
Conversation
Screen readers announce a table header cell with no text as an unnamed column, and axe reports it as empty-table-header. - clidocgen writes "Property | Value" over each option's metadata table instead of an empty header row; the CLI reference is regenerated. - The port-forwarding CORS matrix labels its corner cells (From user, From workspace, To user, To workspace, To app). - Four Markdown matrices get a corner label, byte-identical to #30873. - docshtmlcheck (make lint/docs-html) now fails on empty header cells in Markdown pipe tables and raw HTML tables, naming the file, line, and the table's first header. Assisted-by: AI
errcheck and revive flagged the discarded ast.Walk and strings.Builder errors in the table check. Neither visitor can fail, so walk the tree with a small pre-order helper instead. Assisted-by: AI
The main merge brought in the new secret list page, generated before the Property | Value header, so the merge left its --column table empty. Assisted-by: AI
…mbed or form elements Thirty-two axe HTML rules check ARIA attributes, roles, tabindex, lang values, frames, objects, image maps, form controls, and meta refresh. No docs page uses any of them today, so those rules have nothing to check. Rejecting the elements and attributes keeps it that way, which is cheaper and more reliable than mirroring each rule, and keeps the coverage after the axe licence ends. The elements stay in allowedElements so authors get a message that explains why the element doesn't belong, not the generic unknown-element one, and the end tag still balances. Assisted-by: AI
The guide told authors to mark a decorative image with the Markdown form ``, but markdownlint MD045 rejects a Markdown image with empty alt text, so following the guide failed the docs lint. A raw `<img alt="">` passes MD045 and still tells screen readers to skip the image. No docs page uses the old form. Assisted-by: AI
The axe Linter checks only heading-order in Markdown, and markdownlint MD001 already covers that for Markdown headings. These rules cover what neither sees, so the coverage is owned and outlasts the licence: - HeadingOrder counts raw <hN> headings, such as the ones the API reference generator emits, which MD001 ignores. It stays quiet on a Markdown heading MD001 already reports, so one skip gives one finding. - EmptyHeading flags headings with no text, which no current check catches. - LinkName flags links with no text, including links around an image with empty alt text. MD042 checks only the destination. All three are raw-scope scripts that skip front matter, fenced code, HTML comments, and inline code, and report nothing on the current corpus, so they ship at error under the zero-baseline doctrine. The checks table also gains a row for the docshtmlcheck element and attribute guard, and the coverage counts move the link-text section from planned to tool-checked. Assisted-by: AI
…le headers goldmark keeps an entity such as as literal source text until it renders, so a pipe header cell or the Markdown between <th> blocks holding only looked non-empty and passed, while axe still reports it because U+00A0 trims to nothing. Text nodes are now run through UnescapeString, except inside a code span, where the entity renders literally and is real text. axe's has-visible-text also counts an image's alt text, so an <img alt> in a <th> or a pipe header cell, and an autolink or code block between <th> blocks, no longer read as empty. A table nested inside a <th> still does, and the README lists that under Limitations. The README intro and "How it works" now describe the table check too. Assisted-by: AI
…I notes to the template run derived the HTML count as reportFindings' total minus the table findings, which only worked because reportFindings lumped table findings in with HTML ones, and its doc comment no longer said what it returned. reportFindings now returns a count per kind. Sorting the merged findings by line also moved line-0 stale-allowlist findings ahead of the content findings, where they used to come last; they sort last again. On a CLI reference page the generated-page note sent authors to codersdk and swagger, but a CLI page comes from --help text and scripts/clidocgen/command.tpl, where an empty option-table header would be fixed. The note now names those for CLI pages. Assisted-by: AI
… table Without a scope, a <th> in a row with no data cells is a column header, so From user and From workspace, which span the first three columns, became column headers for the body's label columns alongside To user, To workspace and To app. A screen reader on "Alice" announced "To user, From workspace, From user", which contradicts itself. The From cells now have scope="row" and the other header-row cells scope="col", so each label stays on its own header row. The body's user, workspace and app labels become row headers, so each check or cross mark is announced with both its destination and its origin. The third header row puts App A to App D beside the To labels with nothing saying they are the origin apps, so a caption states that columns are the origin and rows the destination, matching the From and To labels the table already uses. Assisted-by: AI
…tion A style guide section enforced by the docs HTML checker had no way to say so: styleclaims only read markdownlint, MD rules, Vale rules and scripts/check_emdash.sh as tool citations, so a footer naming scripts/docshtmlcheck classified as documentation-only and the coverage table could not count it. Assisted-by: AI
The checks table row for empty-table-header pointed at no rule section, because the formatting guide's Tables section was documentation-only, and the counts below the table still said 9 checked rules. Tables now states the header-text rule with an enforcement footer citing scripts/docshtmlcheck, and the counts move to 10 checked and 45 documentation-only. The row's Tool column now names make lint/docs-html, matching the make lint/emdash row, the paragraph on which checks fail the build includes it, and the Makefile comment and echo for lint/docs-html mention table headers. Assisted-by: AI
…owned-checks Brings in the review fixes on the base branch. reportFindings now returns a count per kind, so the guard findings get their own guard count in issueCounts instead of being subtracted from the HTML total in run. In the style guide, both docshtmlcheck rows name make lint/docs-html, and the counts combine both branches: the Formatting > Tables rule from the base and the accessibility rules from this branch make 11 tool-checked, 24 planned and 45 documentation-only. Assisted-by: AI
…nd Makefile The checker README intro and the lint/docs-html comment and echo listed the HTML and table-header checks but not the disallowed element and attribute guard, which runs in the same target. Assisted-by: AI
…headers # Conflicts: # docs/.style/style-guide/README.md
…to vigilante/docs-a11y-owned-checks # Conflicts: # docs/.style/style-guide/README.md
Main landed the empty-table-header check and the CORS caption from the table-headers work this branch carried, plus the docs-manifest citation in styleclaims. Keep main's versions of those and re-apply this branch's disallowed-markup guard and the three Vale rows on top. Recount the style guide coverage: Link text is now tool-checked, so Accessibility and inclusion moves to 7 tool-checked and the total to 22. Assisted-by: AI
| So the 25 rows in the table above name 29 checks, because the markdownlint row bundles 4 and the disallowed-markup row bundles 2. | ||
| The disallowed-markup checks guard against markup no rule section covers, and the other 27 checks cover 24 sections: each check counts under the section that owns it rather than under every section that mentions it. |
There was a problem hiding this comment.
Blocking: The counting arithmetic here (29 checks, 27 checks, 24 sections) is maintainer bookkeeping. A contributor who reads this page to learn what tooling checks, and what to apply by reading, does not need it, and the table plus the classification method above already carry that task. (Reader Advocate, rule: docs/.style/style-guide/audience-and-scope.md#give-the-audience-only-what-it-needs)
| So the 25 rows in the table above name 29 checks, because the markdownlint row bundles 4 and the disallowed-markup row bundles 2. | |
| The disallowed-markup checks guard against markup no rule section covers, and the other 27 checks cover 24 sections: each check counts under the section that owns it rather than under every section that mentions it. |
| | `MD001`, `MD025`, `MD040`, `MD045` | markdownlint | `error` | All Markdown | Heading increments, single H1, fence language, missing alt text | | ||
| | `scripts/check_emdash.sh` | `make lint/emdash` | `error` | Repository | Em-dash, en-dash, and `--` as punctuation | | ||
| | `empty-table-header` | `make lint/docs-html` | `error` | `docs/**`, including generated pages | Table header cells with no text, in Markdown and HTML tables | | ||
| | `disallowed-element`, `disallowed-attribute` | `make lint/docs-html` | `error` | `docs/**`, including generated pages | ARIA, `role`, `tabindex`, and `lang` attributes, and `iframe`, `object`, `area`, form control, and `meta` elements | |
There was a problem hiding this comment.
The disallowed-markup row lists "form control" elements but omits <form>, which scripts/docshtmlcheck/guard.go also rejects. A reader cannot tell from this row that <form> is blocked. (Fact Checker)
Replace "form control" with the full element list, as scripts/docshtmlcheck/README.md does: iframe, object, area, form, input, select, textarea, button, and meta. Widen the column when you do, because make lint/docs table formatting will flag the longer cell.
| <img src="../../images/decorative/divider.png" alt=""> | ||
| ``` | ||
|
|
||
| Use a raw `<img>` with `alt=""` for a decorative image, not the Markdown `` form. |
There was a problem hiding this comment.
A reader who follows this guidance may reach for role="presentation" or aria-hidden="true" on the <img>. The page does not say the docs HTML check rejects those attributes, so the reader learns it only from a failing CI run. (Newcomer)
| Use a raw `<img>` with `alt=""` for a decorative image, not the Markdown `` form. | |
| Use a raw `<img>` with `alt=""` for a decorative image, not the Markdown `` form. | |
| The docs HTML check rejects `role`, `tabindex`, `lang`, and `aria-*` attributes, so `alt=""` is the only way to mark an image as decorative. |
Documentation CheckBlocking
Design notes
Findings for agents- id: audience-1
persona: audience
class: rule
blocking: true
file: docs/.style/style-guide/README.md
line: 109
quote: "So the 25 rows in the table above name 29 checks, because the markdownlint row bundles 4 and the disallowed-markup row bundles 2."
evidence:
- docs/.style/style-guide/audience-and-scope.md#give-the-audience-only-what-it-needs
rule: docs/.style/style-guide/audience-and-scope.md#give-the-audience-only-what-it-needs
problem: The check-count arithmetic is maintainer bookkeeping that changes nothing the contributor sees, types, or does; the table and the classification method above already carry the task.
fix: Cut the two sentences so the landing page ends at the classification method.
verified: true
- id: accuracy-1
persona: accuracy
class: suggestion
blocking: false
file: docs/.style/style-guide/README.md
line: 59
quote: "ARIA, `role`, `tabindex`, and `lang` attributes, and `iframe`, `object`, `area`, form control, and `meta` elements"
evidence:
- scripts/docshtmlcheck/guard.go:27
- scripts/docshtmlcheck/README.md:32
rule: null
problem: The disallowed-markup row omits the `<form>` element, which the guard also rejects, so a reader cannot tell from this row that `<form>` is blocked.
fix: Name the full element list, as the tool README does.
verified: true
- id: learner-1
persona: learner
class: suggestion
blocking: false
file: docs/.style/style-guide/accessibility-and-inclusion.md
line: 195
quote: "Use a raw `<img>` with `alt=\"\"` for a decorative image, not the Markdown `` form."
evidence:
- scripts/docshtmlcheck/guard.go:46
- docs/.style/style-guide/README.md:59
rule: null
problem: The page does not say the docs HTML check rejects `role`, `tabindex`, `lang`, and `aria-*`, which a reader might use on a decorative image, so they learn it only from a failing CI run.
fix: Add a sentence noting the restriction.
verified: trueAutomated review via Coder Agents. Reply to a finding's thread with the reason if the finding is wrong. |
Merge order
This PR was stacked on #30879, which has merged. It now targets
mainand has no remaining dependency.Summary
The axe Linter checks only one rule in Markdown,
heading-order, and markdownlintMD001already 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>headingsscripts/apidocgenemits, whichMD001ignores.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>.docshtmlchecknow rejectsaria-*,role,tabindex, andlangattributes, andiframe,object,area,form,input,select,textarea,button, andmetaelements. 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., whichMD045rejects, to<img src="…" alt="">. No docs page used the old form.main).Design
All three Vale rules are
scriptrules onrawscope, 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'stext.re_findpanics on a group that didn't match.Coder.HeadingOrderis built to agree withMD001without 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 thatMD001already reports (a skip measured against the previous Markdown heading) and reports the skipsMD001can'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,MD001reports 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
docshtmlcheckguard is a separateguard.gothat runs on each start tag the existing tokenizer already walks. The elements stay inallowedElements, 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 includedformalongside 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.iniand 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 skipsMD001reports, on#lines in front matter, fenced code, and an HTML comment, and on a clean sequence. markdownlint on the same file reported only the twoMD001lines, so no line got both.Coder.EmptyHeading: reported##,### ###,<h2></h2>,<h3> </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 ). 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.HeadingOrder0,Coder.EmptyHeading0,Coder.LinkName0,docshtmlcheckguard 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 beforeguard.goexisted. They cover each element, each attribute (including case-insensitive names and attributes wrapped across lines), lookalike names such asdata-role, code and comment exclusion, the reported line and message, and therunexit 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.iniand the rule files.make lint/emdash: clean.pnpm check-docs(markdownlint and table formatting): 0 errors across 515 files.docs/with--no-exit, run directly rather than throughmake lint/prosebecause 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.