fix(scripts/docshtmlcheck): decode entities and count alt text in table 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 &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
This commit is contained in:
Nick Vigilante committed 2026-10-16 15:21:34 -04:00
1 parent 4933a37f29
commit cfd29a2160
3 files changed
+104 -9

No files matched your search

+9 -5
View File
@@ -1,8 +1,7 @@
# docshtmlcheck
`docshtmlcheck` fails CI when Markdown under `docs/` contains invalid inline
HTML that the documentation site's renderer silently drops or mangles. It runs
as `make lint/docs-html` (part of `make lint`).
`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
@@ -24,8 +23,9 @@ as `make lint/docs-html` (part of `make lint`).
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>` and `<th><br></th>` are reported.
Markdown between the HTML blocks of a `<th>` counts as its text.
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`.
@@ -45,6 +45,9 @@ 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:
@@ -55,6 +58,7 @@ A few gaps are accepted because no docs page hits them today:
- 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
+48 -4
View File
@@ -29,8 +29,9 @@ type headerCell struct {
// checkTables returns a finding for every table header cell with no text, in
// both GFM pipe tables (the header row) and raw HTML tables (any <th>). Text is
// whatever a reader would hear: entities such as &nbsp; are decoded and
// whitespace is trimmed, so <th>&nbsp;</th> and <th><br></th> count as empty.
// Tables inside code blocks and code spans are ignored.
// whitespace is trimmed, so <th>&nbsp;</th> and <th><br></th> count as empty,
// while an image's alt text, an autolink, and code count as text. Tables
// inside code blocks and code spans are ignored.
func checkTables(src []byte) []finding {
doc := goldmark.New(goldmark.WithExtensions(extension.Table)).Parser().Parse(text.NewReader(src))
t := &tableChecker{c: checker{src: src, lineStarts: lineStarts(src)}}
@@ -51,9 +52,15 @@ func checkTables(src []byte) []finding {
case *ast.Text:
// Markdown between the raw-HTML blocks of an open <th>, such as
// <th>\n\n**Feature**\n\n</th>, is that cell's text.
t.addText(string(node.Segment.Value(src)))
t.addText(textValue(node, src))
case *ast.String:
t.addText(string(node.Value))
case *ast.AutoLink:
t.addText(string(node.Label(src)))
case *ast.FencedCodeBlock, *ast.CodeBlock:
for _, seg := range segmentsOf(n.Lines()) {
t.addText(string(seg.Value(src)))
}
}
return true
})
@@ -97,17 +104,52 @@ func inlineText(n ast.Node, src []byte) string {
preorder(n, func(n ast.Node) bool {
switch node := n.(type) {
case *ast.Text:
b = append(b, node.Segment.Value(src)...)
b = append(b, textValue(node, src)...)
case *ast.String:
b = append(b, node.Value...)
case *ast.AutoLink:
b = append(b, node.Label(src)...)
case *ast.RawHTML:
tokenizeSegments(src, segmentsOf(node.Segments), func(int) int { return 0 }, func(z *html.Tokenizer, tt html.TokenType, raw []byte, _ int) {
if (tt == html.StartTagToken || tt == html.SelfClosingTagToken) && strings.EqualFold(rawTagName(raw), "img") {
b = append(b, ' ')
b = append(b, imgAlt(z)...)
}
})
}
return true
})
return string(b)
}
// textValue returns the text of a Markdown text node with entities decoded.
// goldmark keeps &nbsp; as literal source text until it renders, so without
// decoding a cell holding only &nbsp; would look non-empty. Text in a code
// span renders literally, so `&nbsp;` there stays six visible characters.
func textValue(n *ast.Text, src []byte) string {
v := string(n.Segment.Value(src))
if _, ok := n.Parent().(*ast.CodeSpan); ok {
return v
}
return html.UnescapeString(v)
}
// imgAlt returns the alt attribute of the img start tag z is on, which a
// screen reader announces as the image's text. It must run after rawTagName
// has read the raw token, because the tokenizer lowercases attribute names
// in place.
func imgAlt(z *html.Tokenizer) string {
for {
key, val, more := z.TagAttr()
if string(key) == "alt" {
return string(val)
}
if !more {
return ""
}
}
}
// preorder visits n and its descendants in document order. visit returns
// false to skip a node's children. Unlike ast.Walk it has no error path,
// because none of these visitors can fail.
@@ -130,6 +172,8 @@ func (t *tableChecker) scanHTML(segs []text.Segment) {
t.addText(string(z.Text()))
case html.StartTagToken, html.SelfClosingTagToken:
switch strings.ToLower(rawTagName(raw)) {
case "img":
t.addText(imgAlt(z))
case "table":
t.inTH = false
t.tables = append(t.tables, nil)
+47
View File
@@ -68,6 +68,53 @@ func TestCheckTables(t *testing.T) {
name: "html table inside a fenced code block is ignored",
src: "```html\n<table><tr><th></th></tr></table>\n```\n",
},
{
name: "pipe header holding only a non-breaking space entity",
src: "| &nbsp; | A |\n| --- | --- |\n| a | b |\n",
want: []want{{line: 1, first: "A"}},
},
{
name: "pipe header holding only a numeric non-breaking space entity",
src: "| &#160; | A |\n| --- | --- |\n| a | b |\n",
want: []want{{line: 1, first: "A"}},
},
{
name: "html th whose Markdown between blocks is only a non-breaking space",
src: "<table>\n<tr>\n<th>\n\n&nbsp;\n\n</th>\n<th>Name</th>\n</tr>\n</table>\n",
want: []want{{line: 3, first: "Name"}},
},
{
// A code span renders its content literally, so `&nbsp;` is the
// six visible characters, not a space.
name: "an entity inside a code span is text",
src: "| `&nbsp;` | A |\n| --- | --- |\n| a | b |\n",
},
{
name: "html th holding only an image with alt text",
src: "<table><tr><th><img alt=\"Logo\" src=\"x.png\"></th></tr></table>\n",
},
{
name: "html th holding only an image with empty alt text",
src: "<table><tr><th><img alt=\"\" src=\"x.png\"></th><th>Name</th></tr></table>\n",
want: []want{{line: 1, first: "Name"}},
},
{
name: "pipe header holding only a raw image with alt text",
src: "| <img alt=\"Logo\" src=\"x.png\"> | A |\n| --- | --- |\n| a | b |\n",
},
{
name: "pipe header holding only a raw image with empty alt text",
src: "| <img alt=\"\" src=\"x.png\"> | A |\n| --- | --- |\n| a | b |\n",
want: []want{{line: 1, first: "A"}},
},
{
name: "html th whose Markdown between blocks is an autolink",
src: "<table>\n<tr>\n<th>\n\n<https://coder.com>\n\n</th>\n</tr>\n</table>\n",
},
{
name: "html th whose Markdown between blocks is a fenced code block",
src: "<table>\n<tr>\n<th>\n\n```sh\ncoder login\n```\n\n</th>\n</tr>\n</table>\n",
},
{
name: "every header empty names no first header",
src: "<table><tr><th></th></tr></table>\n",