forked from
anil.recoil.org/monopam-myspace
My aggregated monorepo of OCaml code, automaintained
Mark custom inlines shipped and document simplified approach
Records the Raw_markup-piggyback design as the actual implementation;
keeps the original clean-AST sketch as a deferred follow-up.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+45
-1
+45
-1
docs/plans/2026-04-15-odoc-custom-inlines.md
+45
-1
docs/plans/2026-04-15-odoc-custom-inlines.md
···
1
1
# Custom Inline Extensions for Odoc
2
2
3
-
**Status:** Planned
3
+
**Status:** Shipped (2026-04-15) — simplified implementation
4
4
**Date:** 2026-04-15
5
+
6
+
## Shipped
7
+
8
+
The implementation uses a lighter approach than originally sketched:
9
+
instead of a new AST variant, inline extensions ride on the existing
10
+
`Raw_markup` variant with a synthetic target prefix (`odoc-ext:`).
11
+
12
+
- Lexer rule: `{&name payload}` emits
13
+
`Raw_markup (Some ("odoc-ext:" ^ name), payload)` — no new token
14
+
type. One rule added in `odoc/src/parser/lexer.mll`.
15
+
- HTML generator: `raw_markup` in `odoc/src/html/generator.ml`
16
+
detects the prefix and dispatches to the inline-handler registry.
17
+
Falls back to emitting payload raw if no handler is registered.
18
+
- Registry: `register_inline_handler` / `find_inline_handler` +
19
+
`inline_extension_target_prefix` constant in
20
+
`odoc/src/extension_registry/odoc_extension_registry.ml`.
21
+
- Plugin API: `module type Inline_Extension` (prefix + `to_html :
22
+
string -> string`) and `Registry.register_inline` in
23
+
`odoc/src/extension_api/odoc_extension_api.ml`.
24
+
25
+
Total: ~180 LOC across 5 files, no AST changes, no document-IR
26
+
changes, no backend pattern-match audit. The Raw_markup target is
27
+
lightly punned but fully reversible if we ever want a clean
28
+
`` `Extension `` AST variant.
29
+
30
+
Smoke-test plugins in `odoc-jons-plugins`:
31
+
32
+
- `{&kbd Ctrl-K}` → `<kbd>Ctrl-K</kbd>`
33
+
- `{&margin an aside about X}` → `<span class="margin-note">…</span>`
34
+
35
+
Both verified end-to-end after installing the patched odoc and
36
+
reinstalling the plugin.
37
+
38
+
## Not shipped
39
+
40
+
The originally-sketched new AST variant, separate token type, and
41
+
document-IR change are all deferred. They buy cleaner semantics (e.g.
42
+
for non-HTML backends that might want to dispatch on the variant
43
+
directly) but are not needed for the inline extensions to work. The
44
+
sketch below remains as documentation of that larger design.
45
+
46
+
---
47
+
48
+
## Original sketch (deferred)
5
49
6
50
## Problem
7
51