Getting started

executable.md runs markdown documents as executable workflows using the xmd command. This page gets you from install to your first run.

Install

Install the standalone xmd binary (macOS / Linux):

curl -fsSL https://executable.md/install.sh | sh

Or, for Deno users, run it straight from JSR:

deno run -A jsr:@executablemd/cli run doc.md

Prebuilt binaries for every platform are on the releases page. The binary is self-contained — no Node or Deno needed to run it.

From npm

xmd is published to npm as @executablemd/cli:

npm install -g @executablemd/cli

No registry configuration is needed — every @executablemd package resolves from the default npm registry.

Your first document

A document is a component. Frontmatter becomes meta, capitalized JSX tags expand other markdown files, and fenced blocks marked exec run and render their output.

README.md

---
title: My Project
---

# {meta.title}

<Greeting name="world" />

```bash exec
ls ./src
```

Run it:

xmd run README.md

Write a diagnostic journal

Pass --journal to write a JSONL trace of the run to a new file for troubleshooting. The path must not already exist, and the trace is never replayed.

xmd run README.md --journal .xmd/events.jsonl

Useful flags

--journal, -j — write current-run journal entries to a new JSONL file (the path must not exist).
--verbose, -V — print journal entries to stderr while running.
--component-dir — add component search directories (defaults to components and .).

Next: Components →