From ddc4716f114518dd3a5a0aa094ca67e82bf2b297 Mon Sep 17 00:00:00 2001 From: mscherer Date: Thu, 5 Feb 2026 12:36:18 +0100 Subject: [PATCH 1/2] Extend caption syntax to images and block quotes Generalize the existing table caption syntax (^ caption text) to also support images and block quotes: - Image + caption: wraps in
with
- Block quote + caption: wraps in
with
, useful for attributions - Table caption behavior is unchanged ( element) Extract the caption rules into a dedicated "Caption" section in the spec for clarity, replacing the table-specific caption paragraph. Addresses #28 and #31. --- doc/syntax.md | 40 ++++++++++++++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 6 deletions(-) diff --git a/doc/syntax.md b/doc/syntax.md index 2425182..365a9ad 100644 --- a/doc/syntax.md +++ b/doc/syntax.md @@ -673,14 +673,42 @@ verbatim spans; these do not count as cell separators: | just two \| `|` | cells in this table | -You can attach a caption to a table using the following syntax: +Tables support captions; see [Caption] below. - ^ This is the caption. It can contain _inline formatting_ - and can extend over multiple lines, provided they are - indented relative to the `^`. +### Caption -The caption can come directly after the table, or there can -be an intervening blank line. +A caption can be attached to a table, an image, or a block quote by +placing a line starting with `^` followed by a space after the element. +The caption can come directly after the element, or there can be an +intervening blank line. The caption text is parsed as inline content +and can extend over multiple lines, provided they are indented relative +to the `^`. + +A table caption produces a `` element inside the table: + + | fruit | price | + |--------|------:| + | apple | 4 | + ^ Fruit prices in the market + +When a paragraph contains only an image and is followed by a caption, +the image and caption are wrapped in a `
` element with a +`
`: + + ![Sunset over the ocean](sunset.jpg) + ^ A beautiful sunset captured at the beach + +A block quote followed by a caption is wrapped in a `
` element +with a `
`, which is useful for attributions: + + > To be or not to be, that is the question. + ^ William Shakespeare, Hamlet + +Multi-line captions are supported: + + ![Historic photo](apollo.jpg) + ^ This photograph was taken in 1969 + during the Apollo 11 mission. ### Reference link definition From e19233c280ab87243c6918ad3240b5457e827e99 Mon Sep 17 00:00:00 2001 From: mscherer Date: Fri, 6 Feb 2026 00:27:42 +0100 Subject: [PATCH 2/2] Use semantic-first language for caption documentation Lead with semantic descriptions ('provides a title or description', 'is associated with', 'becomes a figure'), then mention HTML rendering as an example output. This addresses the concern about HTML-dependency in the spec. --- doc/syntax.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/doc/syntax.md b/doc/syntax.md index 365a9ad..50d8ade 100644 --- a/doc/syntax.md +++ b/doc/syntax.md @@ -677,29 +677,34 @@ Tables support captions; see [Caption] below. ### Caption -A caption can be attached to a table, an image, or a block quote by -placing a line starting with `^` followed by a space after the element. -The caption can come directly after the element, or there can be an +A caption provides a title or description for an element. A caption +can be attached to a table, an image, or a block quote by placing a +line starting with `^` followed by a space after the element. The +caption can come directly after the element, or there can be an intervening blank line. The caption text is parsed as inline content and can extend over multiple lines, provided they are indented relative to the `^`. -A table caption produces a `` element inside the table: +For tables, the caption is associated with the table itself: | fruit | price | |--------|------:| | apple | 4 | ^ Fruit prices in the market +When rendered to HTML, this produces a `` element inside +the ``. + When a paragraph contains only an image and is followed by a caption, -the image and caption are wrapped in a `
` element with a -`
`: +the image becomes a figure - a self-contained unit with its caption: ![Sunset over the ocean](sunset.jpg) ^ A beautiful sunset captured at the beach -A block quote followed by a caption is wrapped in a `
` element -with a `
`, which is useful for attributions: +When rendered to HTML, this uses `
` and `
` elements. + +A block quote followed by a caption also becomes a figure, which is +useful for attributions: > To be or not to be, that is the question. ^ William Shakespeare, Hamlet