Workbooks Documentation

Workbooks Documentation

Quick Start

Quick Start

Prerequisites: Elixir ≥ 1.16, Rust stable, the runtime compiled. See Installation if you haven't done that yet.

1. Write a workbook

Create hello.org: 

#+TITLE: Hello

* Hello
  :PROPERTIES:
  :WORKBOOK_VERSION: 1
  :END:

This workbook says hello.

** Greet
   :PROPERTIES:
   :in:  name
   :out: greeting
   :END:

#+begin_src javascript
export function greet(name) {
  return `hello, ${name}!`;
}
#+end_src

2. Inspect the build plan

The build plan is the DAG the runtime uses to wire components. Check it with wb tangle: 

wb tangle hello.org

Output (abbreviated): 

{
  "worlds": [
    {"id": "hello/greet", "lang": "javascript"}
  ],
  "components": [
    {"id": "hello/greet", "world": "hello/greet", "in": ["name"], "out": ["greeting"]}
  ],
  "edges": [],
  "imports": ["name"],
  "exports": ["greeting"]
}

imports are the workbook's inputs (name is unresolved — no upstream component feeds it). exports are values the workbook produces.

3. Render it

Render the workbook to HTML: 

wb publish apply hello.org

This writes .publish_out/index.html. Open it in a browser. The OQL kernel rendered the prose and code blocks; the :in: / :out: properties appear in the component metadata.

If you don't have a publish.org yet, scaffold one first: 

wb publish init
# edit publish.org → set PUBLISH_TARGET, PUBLISH_PROJECT, PUBLISH_DOMAIN
wb publish validate
wb publish apply hello.org

4. Run it in iex

Load the runtime and call the OQL kernel directly: 

cd runtime
iex -S mix

org = File.read!("../hello.org")
Workbooks.OQL.tangle_plan(org)    # → build plan map
Workbooks.OQL.render(org)          # → HTML string

5. Query headlines

wb query (or OQL.parse_headlines/1) returns every heading in the workbook as structured JSON, including their tags, properties, and nesting level: 

wb query hello.org

[
  {"level": 1, "title": "Hello", "tags": [], "properties": {"WORKBOOK_VERSION": "1"}},
  {"level": 2, "title": "Greet", "tags": [], "properties": {"in": "name", "out": "greeting"}}
]

This is the foundation of toolkit discovery: toolkits are workbooks with a :toolkit: tag on their top heading.

Next steps