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:

Content plugin (exists) — odoc-scrollycode-extension/src/scrollycode_extension.ml registers as a code block extension via Registry.register
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:

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:

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

Implementation Pattern#

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

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.

Configure Feed