forked from
anil.recoil.org/monopam-myspace
My aggregated monorepo of OCaml code, automaintained
Record @figure V3 design deferred to post-custom-inlines
V3 (inline-AST-driven caption with native {image:…} detection and
future {linked-image …} custom inline) waits on the odoc custom
inline extension point, since odoc's non_link_inline_element excludes
media and the clean syntax requires {linked-image …}. V1 remains the
working implementation in the meantime.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+27
+27
docs/plans/2026-04-15-native-figures.md
+27
docs/plans/2026-04-15-native-figures.md
···
60
60
61
61
## Design
62
62
63
+
### Future V3 (deferred — depends on custom inlines task)
64
+
65
+
Walk the first paragraph's inline AST instead of parsing strings. Use
66
+
odoc's native `{image:url}` / `{{image:url}alt}` media element as the
67
+
image, render everything else in the paragraph as a rich caption
68
+
(preserving `{i}`, `{b}`, `{{:url}…}`, `{!refs}`):
69
+
70
+
```
71
+
@figure link=https://…/parseff {{image:parseff.png} A screenshot of the parseff site} produced by the {i plugin}.
72
+
```
73
+
74
+
→ `<figure><a><img></a><figcaption>produced by the <em>plugin</em>.</figcaption></figure>`
75
+
76
+
Because `non_link_inline_element` excludes `Media`, native odoc can't
77
+
nest an image inside a link, so the wrapping URL still needs to arrive
78
+
as an attribute prefix. Once the custom-inline extension point lands
79
+
(`docs/plans/2026-04-15-odoc-custom-inlines.md`), a dedicated
80
+
`{linked-image url src alt}` custom inline removes the attribute
81
+
prefix entirely:
82
+
83
+
```
84
+
@figure {linked-image https://…/parseff parseff.png "A screenshot"} produced by the {i plugin}.
85
+
```
86
+
87
+
V3 is deferred until the custom-inline work is done; V1 stays in the
88
+
tree as the working implementation in the meantime.
89
+
63
90
### Syntax (v1 — shipped)
64
91
65
92
```