Interactive OCaml Tutorials — User's Guide#

This guide is for tutorial authors and web developers who want to create interactive OCaml content — live code cells, exercises, and widgets — served as static HTML pages with no server-side component.

How it works#

Authors write documentation in .mld files using odoc's tagged code block syntax. The odoc plugin translates {@ocaml ...} blocks into <x-ocaml> HTML elements. A WebComponent (x-ocaml.js) and a Web Worker (worker.js) handle all interactivity in the browser: editing, execution, autocompletion, and type feedback.

Author writes .mld          odoc plugin            x-ocaml + worker
─────────────────────  ──>  ────────────────  ──>  ─────────────────
{@ocaml exercise           <x-ocaml              WebComponent reads
 id=factorial               mode="exercise"       data attrs, manages
 [let facr n = ...]}        data-id="factorial">  UI, sends code to
                            ...                   worker for execution
                            </x-ocaml>

There is no server-side component beyond serving static files over HTTP.

Universes#

A universe is a self-consistent set of compiled OCaml packages. OCaml requires that all libraries in a universe are built with exactly the same versions of all transitive dependencies — you cannot mix libraries from different build environments.

Each universe is identified by a content hash and has a single entry point: findlib_index.json. This file tells the runtime which compiler version to use and where to find every package's artifacts.

Content sources#

The ocaml.org multiverse — the OCaml package documentation site hosts pre-built universes for published opam packages. Each package version's documentation page links to the correct universe for that package and its dependencies.

Self-hosted — you can generate and host your own universes for custom package sets or private libraries. See the Admin Guide for instructions on using jtw opam or day10 to produce these artifacts. Serve the output directory over HTTP with appropriate CORS headers if loading cross-origin.

Directory layout#

compiler/<ocaml-version>/<hash>/
  worker.js                        -- the OCaml toplevel web worker
  lib/ocaml/
    *.cmi, stdlib.cma.js           -- stdlib artifacts

p/<package>/<version>/<hash>/
  lib/<findlib-name>/
    META, *.cmi, *.cma.js          -- package artifacts

u/<universe-hash>/
  findlib_index.json               -- entry point

All paths include a content hash, making them safe to cache indefinitely.

Authoring tutorials#

Page-level configuration#

Custom tags at the top of the .mld file configure the page:

@x-ocaml.universe https://ocaml.org/universe/5.3.0
@x-ocaml.requires cmdliner, astring
@x-ocaml.auto-execute false
@x-ocaml.merlin false

Cell types#

Code blocks use odoc's tagged code block syntax: {@ocaml <attributes> [...code...]}.

Per-cell attributes#

Execution environments#

Cells sharing an env attribute see each other's definitions. By default, all cells on a page share one environment. Named environments allow isolation when needed:

{@ocaml hidden env=greetings [
let greeting = "Hello"
]}

{@ocaml interactive env=greetings [
Printf.printf "%s, world!\n" greeting
]}

{@ocaml interactive env=math [
(* This cell cannot see 'greeting' *)
let pi = Float.pi
]}

Exercise linking#

Test cells are linked to exercise cells by two mechanisms:

• Positional (default) — a test cell applies to the nearest preceding exercise cell.
• Explicit — use id and for attributes when the test is distant or ambiguous.

Examples#

Interactive tutorial#

A step-by-step walkthrough where cells build on each other:

@x-ocaml.universe https://ocaml.org/universe/5.4.0
@x-ocaml.requires fmt

{1 Working with Fmt}

The [Fmt] library provides composable pretty-printing combinators.

{@ocaml interactive [
let pp_greeting ppf name =
  Fmt.pf ppf "Hello, %s!" name
]}

Try it:

{@ocaml interactive [
Fmt.pr "%a@." pp_greeting "world"
]}

Assessment worksheet#

An exercise with hidden setup, editable skeleton, and visible tests:

{@ocaml hidden [
(* Setup code the student doesn't see *)
let check_positive f =
  assert (f 0 = 1);
  assert (f 1 = 1)
]}

Write an OCaml function [facr] to compute the factorial by recursion.

{@ocaml exercise id=factorial [
let rec facr n =
    (* YOUR CODE HERE *)
    failwith "Not implemented"
]}

{@ocaml test for=factorial [
assert (facr 10 = 3628800);;
assert (facr 11 = 39916800);;
]}

Generated HTML#

The odoc plugin maps attributes directly to HTML data attributes:

<x-ocaml mode="hidden">
(* Setup code the student doesn't see *)
let check_positive f = ...
</x-ocaml>

<p>Write an OCaml function <code>facr</code> to compute the factorial
by recursion.</p>

<x-ocaml mode="exercise" data-id="factorial">
let rec facr n =
    (* YOUR CODE HERE *)
    failwith "Not implemented"
</x-ocaml>

<x-ocaml mode="test" data-for="factorial">
assert (facr 10 = 3628800);;
assert (facr 11 = 39916800);;
</x-ocaml>

The plugin also injects a <script> tag for x-ocaml.js (once per page) and <meta> tags for page-level configuration.

Using x-ocaml outside odoc#

The <x-ocaml> WebComponent works in any HTML page — it doesn't require odoc. You can write the elements by hand:

<!DOCTYPE html>
<html>
<head>
  <meta name="x-ocaml-universe"
        content="https://ocaml.org/universe/5.4.0">
  <meta name="x-ocaml-requires" content="str">
  <script src="https://ocaml.org/jtw/x-ocaml.js" type="module"></script>
</head>
<body>
  <x-ocaml mode="interactive">
  let words = Str.split (Str.regexp " ") "hello world"
  </x-ocaml>

  <x-ocaml mode="exercise" data-id="reverse">
  let reverse lst =
      (* YOUR CODE HERE *)
      failwith "todo"
  </x-ocaml>

  <x-ocaml mode="test" data-for="reverse">
  assert (reverse [1;2;3] = [3;2;1]);;
  </x-ocaml>
</body>
</html>

This makes the system usable with other documentation generators, static site builders, or hand-written HTML.

Client library (advanced)#

For custom integrations that need direct control over the Web Worker, the OcamlWorker JavaScript class provides a programmatic API.

Creating a worker#

import { OcamlWorker } from './ocaml-worker.js';

const indexUrl = './u/UNIVERSE_HASH/findlib_index.json';
const { worker, stdlib_dcs, findlib_index } =
  await OcamlWorker.fromIndex(indexUrl, '.', { timeout: 120000 });

await worker.init({
  findlib_requires: ['fmt'],
  stdlib_dcs,
  findlib_index,
});

Evaluating code#

const result = await worker.eval('List.map (fun x -> x * 2) [1;2;3];;');
console.log(result.caml_ppf);
// val x : int list = [2; 4; 6]

The result object contains:

Other methods#

• complete(code, pos) — autocompletion suggestions at a cursor position
• typeAt(code, pos) — type of the expression at a position
• errors(code) — check code for errors without executing it
• createEnv(name) / destroyEnv(name) — manage isolated execution environments
• terminate() — shut down the web worker

Rich output (MIME values)#

eval() results may include mime_vals — an array of objects with mime_type and data. Libraries that produce graphical output (plotting, diagrams) use this mechanism to display results in the browser. Common types: text/html, image/svg+xml, image/png.

Loading libraries at runtime#

In addition to preloading via findlib_requires, users can load libraries dynamically:

#require "str";;
Str.split (Str.regexp " ") "hello world";;

This works for any library present in the universe's findlib_index.json.

What's next#

• Scrollycode tutorials — scroll-driven code walkthroughs using odoc-scrollycode-extension (already prototyped)
• Interactive widgets — reactive UI elements (sliders, plots, mini-apps) driven by an FRP library running in the Worker (experimental)