# Scrollycode Shell — Implementation Notes

Notes captured during the `scrollycode-and-spa` branch work (2026-03-03)
for when the dedicated scrollycode shell gets built.

## Context

The scrollycode extension has two concerns:
1. **Content plugin** (exists) — `odoc-scrollycode-extension/src/scrollycode_extension.ml`
   registers as a code block extension via `Registry.register`
2. **Shell** (not yet built) — a dedicated page shell for scrollycode
   presentations, where theming belongs

Theming was initially added to the docsite shell but reverted because
the docsite shell shouldn't know about scrollycode-specific concerns.

## Available Infrastructure

### `--config KEY=VALUE` on `odoc html-generate`

Generic config_values support was added to `odoc`:
- `Odoc_html.Config.t` has a `config_values : (string * string) list` field
- `odoc html-generate --config scrollycode.theme=warm` populates it
- Any shell can read it via `Odoc_html.Config.config_values config`

### Three theme CSS files already registered

`odoc-scrollycode-extension/src/scrollycode_themes.ml` (lines 520-529)
registers three themes as support files:

```ocaml
register "warm" warm_css;    (* extensions/scrollycode-warm.css *)
register "dark" dark_css;    (* extensions/scrollycode-dark.css *)
register "notebook" notebook_css;  (* extensions/scrollycode-notebook.css *)
```

Each defines CSS custom properties (`--sc-font-display`, `--sc-bg`,
`--sc-accent`, `--sc-hl-keyword`, etc.) consumed by the structural
`scrollycode.css`.

### Passing `--config` via dune

In `dune-workspace`, `(odoc (html_flags ...))` passes flags to
`odoc html-generate`:

```dune
(env
 (dev
  (odoc
   (html_flags --shell scrollycode --config scrollycode.theme=warm))))
```

## Implementation Pattern

The helper that was prototyped (and reverted from the docsite shell):

```ocaml
let scrollycode_theme_links ~config ~url =
  match
    List.assoc_opt "scrollycode.theme"
      (Odoc_html.Config.config_values config)
  with
  | None -> []
  | Some theme ->
      let support_uri = Odoc_html.Config.support_uri config in
      let css_url =
        file_uri ~config ~url support_uri
          ("extensions/scrollycode-" ^ theme ^ ".css")
      in
      [ Html.link ~rel:[ `Stylesheet ] ~href:css_url () ]
```

This reads `scrollycode.theme` from config_values and emits a `<link>`
for the corresponding theme CSS. Include it in the shell's
`page_creator` head assembly.