jon.recoil.org
this repo has no description
Add implementation notes for future scrollycode shell
Captures the theming pattern, available infrastructure (--config,
theme CSS files, dune-workspace html_flags), and the helper code
prototyped during this branch.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+75
docs/plans/2026-03-03-scrollycode-shell-notes.md
+75
docs/plans/2026-03-03-scrollycode-shell-notes.md
···
1
+
# Scrollycode Shell — Implementation Notes
2
+
3
+
Notes captured during the `scrollycode-and-spa` branch work (2026-03-03)
4
+
for when the dedicated scrollycode shell gets built.
5
+
6
+
## Context
7
+
8
+
The scrollycode extension has two concerns:
9
+
1. **Content plugin** (exists) — `odoc-scrollycode-extension/src/scrollycode_extension.ml`
10
+
registers as a code block extension via `Registry.register`
11
+
2. **Shell** (not yet built) — a dedicated page shell for scrollycode
12
+
presentations, where theming belongs
13
+
14
+
Theming was initially added to the docsite shell but reverted because
15
+
the docsite shell shouldn't know about scrollycode-specific concerns.
16
+
17
+
## Available Infrastructure
18
+
19
+
### `--config KEY=VALUE` on `odoc html-generate`
20
+
21
+
Generic config_values support was added to `odoc`:
22
+
- `Odoc_html.Config.t` has a `config_values : (string * string) list` field
23
+
- `odoc html-generate --config scrollycode.theme=warm` populates it
24
+
- Any shell can read it via `Odoc_html.Config.config_values config`
25
+
26
+
### Three theme CSS files already registered
27
+
28
+
`odoc-scrollycode-extension/src/scrollycode_themes.ml` (lines 520-529)
29
+
registers three themes as support files:
30
+
31
+
```ocaml
32
+
register "warm" warm_css; (* extensions/scrollycode-warm.css *)
33
+
register "dark" dark_css; (* extensions/scrollycode-dark.css *)
34
+
register "notebook" notebook_css; (* extensions/scrollycode-notebook.css *)
35
+
```
36
+
37
+
Each defines CSS custom properties (`--sc-font-display`, `--sc-bg`,
38
+
`--sc-accent`, `--sc-hl-keyword`, etc.) consumed by the structural
39
+
`scrollycode.css`.
40
+
41
+
### Passing `--config` via dune
42
+
43
+
In `dune-workspace`, `(odoc (html_flags ...))` passes flags to
44
+
`odoc html-generate`:
45
+
46
+
```dune
47
+
(env
48
+
(dev
49
+
(odoc
50
+
(html_flags --shell scrollycode --config scrollycode.theme=warm))))
51
+
```
52
+
53
+
## Implementation Pattern
54
+
55
+
The helper that was prototyped (and reverted from the docsite shell):
56
+
57
+
```ocaml
58
+
let scrollycode_theme_links ~config ~url =
59
+
match
60
+
List.assoc_opt "scrollycode.theme"
61
+
(Odoc_html.Config.config_values config)
62
+
with
63
+
| None -> []
64
+
| Some theme ->
65
+
let support_uri = Odoc_html.Config.support_uri config in
66
+
let css_url =
67
+
file_uri ~config ~url support_uri
68
+
("extensions/scrollycode-" ^ theme ^ ".css")
69
+
in
70
+
[ Html.link ~rel:[ `Stylesheet ] ~href:css_url () ]
71
+
```
72
+
73
+
This reads `scrollycode.theme` from config_values and emits a `<link>`
74
+
for the corresponding theme CSS. Include it in the shell's
75
+
`page_creator` head assembly.