## Summary axe reports `empty-table-header` on 116 generated CLI reference pages and several hand-written pages: a header cell with no text is announced by screen readers as an unnamed column. This PR gives every table header cell in `docs/` text, and adds a lint check so empty header cells can't come back. ## How to review this PR - `docs/reference/cli/`: 116 files, these all generate identically, so I would only spot check 2-3 of them and skip the rest - `docs/*` outside of `docs/reference/cli/`: 6 files, normal review of these - `scripts`: 5 files, code review of the Bash and Go files to make sure we're properly inserting headers into each table ## What changed **Generator.** `scripts/clidocgen` wrote an empty header row (`| | |`) over each option's metadata table (Type, Environment, YAML, Default). It now writes `| Property | Value |`. Subcommand tables already had `Name | Purpose` and are unchanged. Regenerated with `make docs/reference/cli/index.md`: 116 files under `docs/reference/cli/` change. The header rows change, and the body rows of each option table are re-padded to the wider first column; the content is otherwise identical. Every option on those 116 pages now shows a visible `Property | Value` header row above Type, Environment, YAML, and Default, so this is a visual change on the docs site as well as a screen reader one. The CLI's own `--help` output doesn't use this template, so it's unchanged. **Audit logs.** `docs/admin/security/audit-logs.md` already has `Field | Tracked` headers on `main` (the generator writes them), so there was nothing to change there; the live-site finding predates that. **Hand-written tables.** - `docs/admin/networking/port-forwarding.md`: the CORS matrix had three empty spanning corner cells. The corner now reads `From user` and `From workspace` (spanning the three row-header columns, beside the Alice/Bob and Workspace rows) and `To user`, `To workspace`, `To app` (over the three row-header columns). The grid is still 3 header rows by 7 columns. The From cells have `scope="row"` and the other header-row cells `scope="col"`, so the From labels don't become column headers for the body's label columns; the body's user, workspace, and app labels are `<th scope="row">`; and a `<caption>` says columns are the origin and rows the destination. - `groups-roles.md`, `airgap.md`, `scale-testing.md`, `workspace-tags.md`: these four corner cells are already filled by #30873. The new check would fail CI without them, so this PR carries the same four lines, byte-identical to #30873 (`Permission`, `Component`, `Scenario`, `Input`), so whichever PR merges second rebases without conflict. If #30873 merges first, these hunks drop out. **New check.** `scripts/docshtmlcheck` (`make lint/docs-html`, part of `make lint`) now also reports `empty-table-header`. I put it there because that checker already parses every Markdown file under `docs/`, generated pages included, with goldmark and tokenizes raw HTML with `golang.org/x/net/html`, and it already runs in CI. A markdownlint custom rule would have needed a new JS rule and HTML parsing there. - Markdown pipe tables: the header row, via goldmark's GFM table extension. - Raw HTML tables: every `<th>`, tracked across HTML blocks, with entities decoded and whitespace trimmed, so `<th></th>`, `<th> </th>`, and `<th><br></th>` are all reported. Markdown between the HTML blocks of an open `<th>` counts as its text. Tables in code blocks are ignored. - Output: `docs/x.md:29: empty-table-header: header cell 1 has no text (table's first header "Auditor")`, plus a summary footer. - The tokenizer loop moved out of `scanNode` into a shared `tokenizeSegments` helper so both checks use it; `scanNode`'s behavior is unchanged. - The style guide's checks table gets one row; the README for the checker describes the rule. ## Testing - Tests first: `TestCheckTables` (now 22 cases) and `TestRunEmptyTableHeader` failed against a stub, then pass. The existing `docshtmlcheck` tests pass unchanged. - `go run ./scripts/docshtmlcheck` on `main` reports 1,561 empty header cells (116 CLI pages, port-forwarding, and the four #30873 tables); on this branch it reports none. - `go test ./scripts/docshtmlcheck/ ./scripts/clidocgen/ ./scripts/docgenenv/`, golangci-lint on the changed packages, `make lint/docs-html lint/docs-manifest lint/docs-gen-filter lint/emdash`, `pnpm run check-docs`, and Vale on the changed hand-written pages all pass. - `make gen` couldn't run to completion locally (no `protoc-gen-go`); CI's gen check covers it. The CLI pages were regenerated with the repo's own target. Review feedback applied incfd29a2160(entities decoded in Markdown text, image alt text and autolinks count as text),709a58f603(per-kind counts, finding order, CLI generator note),8e61ff3afa(CORS matrix scopes and caption), andb807bcbbc7and2871f89bdf(style guide rule section, `make lint/docs-html` in the checks table, coverage counts). Linear: DOCS-1308 --- 🤖 Built with AI assistance.
docshtmlcheck
docshtmlcheck fails CI when Markdown under docs/ contains invalid inline HTML that the documentation site's renderer silently drops or mangles, or a table header cell with no text.
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 (seecontributing/documentation.md). This also covers CLI--helpstrings and Swagger annotations, whose text is generated intodocs/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> </th>,| |, and<th><br></th>are reported. An entity inside a code span is literal text, so` `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 asPermission.
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.