Reference

CLI usage and pointers to the full specification.

CLI

xmd run <document.md> [options]
xmd <document.md> [options]   # run is the default command
xmd run - [options]           # the document is read from standard input
xmd -e '<markdown>' [options]  # an inline document, no file needed

A run takes its root document from exactly one of three inputs: a path, standard input, or one --eval value.

• - — read the whole root document from standard input, to end of file. Only the explicit xmd run - spelling does it. A bare xmd - is the shorthand run form and executes the file named -; xmd run -#Section selects a section of that same file; and --eval - is refused rather than read. Printed errors and source positions report the origin as <stdin>, which is an identity rather than a file: nothing of that name is created, and relative imports and every other relative operation resolve from the directory the command was run in.
• --eval, -e — execute the given markdown as the root document instead of a path. Quote it so the shell passes one argument; printed errors 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.
• --no-secret-detection — turn off credential detection for the whole invocation. Detection is on by default, and refuses to persist a durable event carrying a credential. This is the only spelling that disables it, and a disabled run warns once on standard error that credentials may be persisted. A dangerous diagnostic escape hatch: the normal response to a finding is to fix the code or data flow that produced it.
• --verbose, -V — print journal entries to stderr.
• --include — 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.
• <Let as="name"> binds one name in the current environment — what its children render, or the exact value a value prop names — and renders nothing itself.
• <Json value={...} /> renders one value as two-space JSON text where it is written, or binds that text when as names a binding.
• <Parse schema={...} as="name"> turns the text its children render into a validated value, and renders nothing.
• <If condition={...}> with an optional <Else> expands one branch; the other performs no work.
• <Switch value={...}> holds <Case value={...}> branches and an optional final <Case default> — the first branch whose matcher is === the selector expands, and no other performs any 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:

• Executable MDX specification →
• Project README →
• Issues & feedback →

Status

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