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 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:
1 parent
4933a37f29
commit
cfd29a2160
3 files changed
+104
-9
No files matched your search
@@ -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> </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> </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 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
|
||||
|
||||
|
||||
@@ -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 are decoded and
|
||||
// whitespace is trimmed, so <th> </th> and <th><br></th> count as empty.
|
||||
// Tables inside code blocks and code spans are ignored.
|
||||
// whitespace is trimmed, so <th> </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 as literal source text until it renders, so without
|
||||
// decoding a cell holding only would look non-empty. Text in a code
|
||||
// span renders literally, so ` ` 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)
|
||||
|
||||
@@ -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: "| | A |\n| --- | --- |\n| a | b |\n",
|
||||
want: []want{{line: 1, first: "A"}},
|
||||
},
|
||||
{
|
||||
name: "pipe header holding only a numeric non-breaking space entity",
|
||||
src: "|   | 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 \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 ` ` is the
|
||||
// six visible characters, not a space.
|
||||
name: "an entity inside a code span is text",
|
||||
src: "| ` ` | 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",
|
||||
|
||||
Reference in new issue
Block a user