Workbooks Documentation

Workbooks Documentation

Introduction

Introduction

A workbook is a single .org file. It carries prose, code, data, and a query interface over all three. You write it in Org mode. The runtime renders it, compiles its source blocks to WASM components, wires them together into a build plan, and can publish the result as a self-contained .html file. No build pipeline. No config files. One file in, one URL out.

This documentation site is itself a workbook — rendered by the same OQL kernel that renders yours.

The unit of work

Every workbook has exactly one structural requirement: a top-level heading with :WORKBOOK_VERSION: 1 in its :PROPERTIES: drawer. 

#+TITLE: My Workbook

* My Workbook
  :PROPERTIES:
  :WORKBOOK_VERSION: 1
  :END:

Prose, source blocks, and property drawers live here.

Everything else — headings, source blocks, properties — is standard Org. The runtime understands Org; you do not learn a new format.

What the runtime does

The runtime is an Elixir application (~6 k LOC) that embeds the OQL kernel as a compiled WASM component. On a workbook read it does four things:

  1. Parse — OQL parses the Org source into a structured headline tree.

  2. Plan — OQL emits a build plan: a JSON DAG of WASM worlds, components, and edges derived from the source blocks and their :in: / :out: args.

  3. Execute — wasmtime executes each component in the DAG, feeding outputs to inputs per the edge map.

  4. Render — OQL renders the Org source to HTML for human consumption.

Steps 1–2 are pure (no side effects); 3 involves the WASM sandbox; 4 produces the artifact the browser or wb publish ships.

How this docs site works

Each page in this documentation is an .org file in web/docs/. The nav manifest is web/docs/site.org. Running wb publish site web/docs parses the manifest, renders each linked .org file through the OQL kernel, injects the shared sidebar, and writes a flat dist/ tree that Cloudflare Pages serves.

To update any page: edit its .org file and run wb publish site web/docs again.

What to read next