Multi-file documents & references

reference ./path.wit pulls another file into the document'shoisted

— one flat namespace, visible regardless of order. This is how you split a thesis, report, or manual into chapter files that share one schema.

The reference directive

Put reference ./chapter.wit on its own line. The referenced file's defs and data become available to the whole document:

source

~ master.wit
reference ./one.wit

The keeper is @keeper.name.

~ one.wit
#keeper: { name - Ada }

result

The keeper is Ada.

That renders The keeper is Ada.. Path forms are same-directory ./one.wit, a child directory ./sub/x.wit (nested-subdir), and a parent ../shared.wit (parent-relative).

One flat namespace, hoisted

Multiple references form one namespace, and visibility is transitive — a master that references A which references B can see B's definitions (transitive-references). Because everything is hoisted, the position of the reference line is immaterial: a use that appears before the reference still resolves (forward-then-back).

~ master.wit
The keeper is @keeper.name.

reference ./one.wit

Still renders The keeper is Ada..

Shared schemas and diamonds

Two chapters may both reference a shared schema file; the re-convergence (a diamond) resolves once. This is the idiom for a common set of card, citation, and figure templates used across every chapter.

Self, circular, and missing

A self-reference is a no-op via the already-visited set; a circular pair is handled by cycle detection (circular-references); a missing path is a resolver error (missing-file).

Common mistakes

Expecting a conditional reference — wrapping reference in an (if) is not supported. To include different subsets, choose a different build root (see Faceted content).
Expecting a mid-file reference to scope-limit — it is global and hoisted.
Relative-path confusion — mind ./, ../, and ./sub/.