Skip to content

feat: own the docs accessibility checks the axe Linter doesn't run on Markdown - #30905

Merged
nickvigilante merged 19 commits into
mainfrom
vigilante/docs-a11y-owned-checks
Nov 18, 2026
Merged

nickvigilante merged 19 commits into
mainfrom
vigilante/docs-a11y-owned-checks

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 16, 2026 •

Copy link
Copy Markdown
Collaborator

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.

nickvigilante and others added 7 commits October 15, 2026 16:48
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 `![](image.png)`, 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
@linear-code

linear-code Bot commented Oct 16, 2026

Copy link
Copy Markdown

DOCS-1318

@nickvigilante nickvigilante changed the title feat(docs/.style): own the docs accessibility checks the axe Linter doesn't run on Markdown feat: own the docs accessibility checks the axe Linter doesn't run on Markdown Oct 16, 2026
…le headers

goldmark keeps an entity such as &nbsp; as literal source text until it
renders, so a pipe header cell or the Markdown between <th> blocks holding
only &nbsp; 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
Base automatically changed from vigilante/docs-table-headers to main October 21, 2026 17:58
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
@nickvigilante
nickvigilante marked this pull request as ready for review November 13, 2026 18:24
@nickvigilante
nickvigilante temporarily deployed to main November 13, 2026 18:24 — with GitHub Actions Inactive
@nickvigilante
nickvigilante temporarily deployed to main November 13, 2026 18:25 — with GitHub Actions Inactive
Comment thread docs/.style/style-guide/README.md Outdated
Comment on lines +109 to +110
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Suggested change
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.

Comment thread docs/.style/style-guide/README.md Outdated
| `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 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Suggested change
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.

@coderagents

coderagents Bot commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

Documentation Check

Blocking

  • docs/.style/style-guide/README.md - The check-count arithmetic (29 checks, 27 checks, 24 sections) is maintainer bookkeeping a contributor reading the page does not need; end the landing page at the classification method. This is a contributor style-guide page, not published to coder.com/docs.

Design notes

  • The style-guide check table says the disallowed-markup check catches "form control" elements but omits <form>, which the guard also rejects. It is incompleteness, not inaccuracy, so it is a suggestion: name the full element list, as scripts/docshtmlcheck/README.md does.
  • The decorative-image section tells a reader to use a raw <img> with alt="" but does not mention that the docs HTML check rejects role, tabindex, lang, and aria-*, which a reader might reach for on a decorative image.
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: true

Automated review via Coder Agents. Reply to a finding's thread with the reason if the finding is wrong.

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@nickvigilante
nickvigilante temporarily deployed to main November 17, 2026 19:22 — with GitHub Actions Inactive
@nickvigilante
nickvigilante merged commit b2474d1 into main Nov 18, 2026
29 of 30 checks passed
@nickvigilante
nickvigilante deleted the vigilante/docs-a11y-owned-checks branch November 18, 2026 17:24
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 18, 2026

This branch had an error being deployed

1 failed and 1 inactive deployments
docs-preview — 6665f42d Deployed Nov 18, 2026 by nickvigilante via cleanup #213
main — 6665f42d Deployed Nov 18, 2026 by nickvigilante via cla #259715
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants