forked from
anil.recoil.org/monopam-myspace
My aggregated monorepo of OCaml code, automaintained
1# Scrollycode Shell — Implementation Notes
2
3Notes captured during the `scrollycode-and-spa` branch work (2026-03-03)
4for when the dedicated scrollycode shell gets built.
5
6## Context
7
8The scrollycode extension has two concerns:
91. **Content plugin** (exists) — `odoc-scrollycode-extension/src/scrollycode_extension.ml`
10 registers as a code block extension via `Registry.register`
112. **Shell** (not yet built) — a dedicated page shell for scrollycode
12 presentations, where theming belongs
13
14Theming was initially added to the docsite shell but reverted because
15the docsite shell shouldn't know about scrollycode-specific concerns.
16
17## Available Infrastructure
18
19### `--config KEY=VALUE` on `odoc html-generate`
20
21Generic 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)
29registers three themes as support files:
30
31```ocaml
32register "warm" warm_css; (* extensions/scrollycode-warm.css *)
33register "dark" dark_css; (* extensions/scrollycode-dark.css *)
34register "notebook" notebook_css; (* extensions/scrollycode-notebook.css *)
35```
36
37Each 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
43In `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
55The helper that was prototyped (and reverted from the docsite shell):
56
57```ocaml
58let 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
73This reads `scrollycode.theme` from config_values and emits a `<link>`
74for the corresponding theme CSS. Include it in the shell's
75`page_creator` head assembly.