Reference

CLI usage and pointers to the full specification.

CLI

xmd run &lt;document.md&gt; [options]
xmd &lt;document.md&gt; [options]   # run is the default command
xmd -e &#39;&lt;markdown&gt;&#39; [options]  # an inline document, no file needed

--eval, -e — execute the given markdown as the root document instead of a path. Exactly one of the two is required. Quote it so the shell passes one argument; diagnostics report the source as <eval>, and relative paths resolve from the current directory.
--journal, -j — write a diagnostic JSONL trace of the run to a new file. The path must not exist and is never replayed.
--verbose, -V — print journal entries to stderr.
--component-dir — add a component search directory (repeatable).
--raw — output raw markdown without normalization or terminal formatting.

Document model

Frontmatter becomes meta.
Capitalized JSX tags become component invocations; <Content /> is a child slot.
Text segments support {meta.key} and {props.key} interpolation.
<If condition={...}> with an optional <Else> expands one branch; the other performs no work.
<Loop max={n}> expands its body at most n times, sharing the enclosing bindings; <Break /> exits the nearest loop and skips the rest of the iteration.
A fenced block is executable iff exec or eval appears after the language word.

Full specification

The authoritative design and behavior spec (draft) lives in the repository:

Status

executable.md is an early, first public release and a draft spec. Expect rough edges, and please open an issue with feedback.