Speculative Docs as Notebooks

Writing the docs as notebook documents

Speculative. A proposal, not adopted.

Much of the site is already data the engine reads:

• reference examples are rows in reference/<Head>/examples.tsv, with their forms derived;
• component stories are YAML beside the components (packages/components/reference/<Name>.stories.yaml);
• record prose and captions go through the prose boxes (web/.vitepress/prose.ts), so $…$ islands and [[Symbol]] references render one way everywhere;
• a guide page can already cite an example by its address (#example/<id>).

The idea

A guide is a notebook document: markdown cells for the prose, expression cells for the mathematics (written as Vdom markup or Epsil), evaluated and pinned at build time like the generated reference data. Demos come from examples and stories cited by id rather than inlined snippets, so every demo on the site is tested and scanned against the oracles.

What it would buy

Every demo becomes a test. A change to a printer or to the markup reaches the whole site. The docs exercise the notebook the way readers will.

What it costs

• Build time: evaluating whole pages at build adds to a site build that is mostly bundling today.
• Authoring: whether a notebook document is easier to write than markdown with $…$ islands, and which pages are worth converting first (the guides, the explore pages).