Executable documentation

Runnable QQL belongs in the qqlExample component:

QQLDescribe the behaviorTry in playground↗

QUERY TEXT 'example'
FROM docs
USING dense
LIMIT 5;

The component provides consistent presentation and preserves the fenced source exactly. Do not use raw qql or sql fences outside qqlExample for runnable statements: the verifier rejects them so examples cannot silently bypass the executable contract.

Run the verifier

Documentation contract check

cd website pnpm validate:qql

The command:

1. creates an isolated temporary output directory;
2. builds crates/qql-wasm from the current checkout for Node.js;
3. extracts every qqlExample from the Markdoc tree;
4. calls the WASM parse export on the complete example, then the analyze export to confirm every statement also plans to a route;
5. rejects bare qql/sql fences outside qqlExample and re-checks every fixtures/valid/*.qql playground preset;
6. reports the source file and line for every failure;
7. removes the temporary generated package.

This detects grammar drift — and plan-level regressions — without depending on a previously generated or published SDK package.

Full site check

Validate and build

cd website pnpm check

pnpm check runs the verifier, rebuilds the WASM package, produces the static site, and then checks every same-site /docs/… link and #fragment against the generated HTML (scripts/check-site-anchors.mjs).

Keep intentionally invalid syntax in prose or an ebnf/text block, clearly labelled as invalid. Raw qql/sql fences are rejected by the verifier, so runnable statements cannot silently bypass the executable contract.