Skip to content

Commit b7b5f00

Browse files
committed
plans 87, 88: tighten failure-mode and CommonMark wording
Address two Copilot review points: - plan 87: described the non-GFM render of `> [!NOTE]` as a "silent failure", but the literal marker text is visibly rendered — that is a visible failure. Reword to match. - plan 88: the phrase "None are part of CommonMark, GFM, or goldmark" was ambiguous — `[TOC]` IS valid CommonMark syntax as a shortcut reference link. Reword to make clear that none of the four tokens are standardized as TOC directives, while `[TOC]` remains a valid (but differently-resolved) link shorthand.
1 parent 7c7a4d0 commit b7b5f00

2 files changed

Lines changed: 20 additions & 10 deletions

File tree

plan/87_markdown-flavor-github-alerts.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,8 +47,10 @@ renders as literal text inside a blockquote:
4747

4848
becomes a blockquote whose first line is the
4949
literal string `[!NOTE]`. The author intended a
50-
styled callout; the reader sees unstyled text.
51-
This is a silent failure.
50+
styled callout; the reader sees unstyled text
51+
with the marker token visible inside the
52+
blockquote. The failure is visible, not silent,
53+
but the author's intent is still lost.
5254

5355
### Why not a generic container rule
5456

plan/88_toc-directive-migration.md

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -35,14 +35,22 @@ Four TOC directive variants appear in the wild:
3535
VitePress
3636
- `${toc}` — some VitePress configurations
3737

38-
None are part of CommonMark, GFM, or goldmark.
39-
On those renderers the directive does not
40-
expand into a TOC; it renders as literal text.
41-
The exact output depends on the pattern:
42-
43-
- `[TOC]` without a matching link reference
44-
definition renders as the literal string
45-
`[TOC]` (goldmark emits a "no matching link
38+
None are standardized TOC directives in
39+
CommonMark, GFM, or goldmark. `[TOC]` is still
40+
valid CommonMark syntax — a shortcut reference
41+
link — so it only renders as literal text when
42+
no matching `[TOC]: <url>` definition is
43+
present; with a definition, it renders as a
44+
link. The other three tokens are not valid
45+
link-reference shorthand and always render as
46+
literal text. On those renderers no token in
47+
this set expands into a generated TOC.
48+
49+
Concrete render outputs when no link reference
50+
is present:
51+
52+
- `[TOC]` renders as the literal string `[TOC]`
53+
(goldmark emits a "no matching link
4654
reference" fallback, which is verbatim text)
4755
- `[[_TOC_]]` renders as `[[_TOC_]]` inside a
4856
paragraph

0 commit comments

Comments
 (0)