Skip to content

Extend caption syntax to images and block quotes #373

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dereuromark wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Extend caption syntax to images and block quotes #373

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ddc4716
Extend caption syntax to images and block quotes
dereuromark Feb 5, 2026
e19233c
Use semantic-first language for caption documentation
dereuromark Feb 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 34 additions & 6 deletions doc/syntax.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<caption>` element inside the table:
Comment thread
dereuromark marked this conversation as resolved.
Outdated

| 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 `<figure>` element with a
`<figcaption>`:

![Sunset over the ocean](sunset.jpg)
^ A beautiful sunset captured at the beach

A block quote followed by a caption is wrapped in a `<figure>` element
with a `<figcaption>`, 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

Expand Down