executable.md — markdown that runs

Markdown that runs.

executable.md treats plain markdown documents as executable workflows — components, runnable code blocks, and in-process Effection operations, all in a file that still renders as normal markdown anywhere.

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

Standalone binary (built with deno compile) · also runs from source on Deno · CLI command: xmd

What it does

Components

Invoke other markdown files with JSX-style tags like <Greeting name="world" />. Frontmatter declares meta and typed props; <Content /> slots wrap children.

Executable blocks

Mark a fence exec to run it as a subprocess, or eval to run it in-process as an Effection operation. The output replaces the block.

Modifier chains

Compose behavior left-to-right: silent, persist, timeout=30s, daemon. The fence info string is a middleware chain.

Diagnostic journals

Pass --journal to write a JSONL trace of the run — component sources, command output, evaluated values, and errors — to a new file for troubleshooting.

Shared bindings

Top-level bindings from eval blocks export automatically to later blocks. Reference them inline as {name} inside any executable block.

LLM providers

Provider components wire up cloud and local models (Anthropic, Ollama, Llamafile) with readiness checks and sampling — no custom runtime glue.

See it

A document is a component. Frontmatter becomes meta, capitalized tags expand other documents, and exec blocks run and render their output.

README.md

---
title: My Project
---

# {meta.title}

<Greeting name="world" />

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

components/Greeting.md

---
emoji: Hello
props:
  name:
    type: string
    required: true
---

{meta.emoji}, {props.name}!

rendered output

# My Project

Hello, world!

main.ts
utils.ts

Diagnostic journals.

Pass --journal to write a JSONL trace of a single run — component sources, command output, evaluated values, and errors. The path must not already exist, and the trace is never replayed: it's for troubleshooting, not recovery. Treat it as potentially sensitive data.

$xmd run doc.md --journal .xmd/events.jsonl

One document, two models.

<AnthropicProvider> and <OllamaProvider> nest inside a single markdown file. <Sample> routes prompts to a cloud model (Claude Opus) and a local model (llama3.2), then combines the results — no orchestration code, just markdown.

packages/core/examples/hello-world.md

---
title: Hello World
---

# {meta.title}

<AnthropicProvider model="claude-opus-4-5">
  <OllamaProvider model="llama3.2">
    <Instruction system="You are a creative comedian.">
      <Sample model="llama3.2">
        Smart: <Sample prompt="Say something smart" model="claude-opus-4-5" />
        Joke:  <Sample prompt="Tell me a joke" model="llama3.2" />
        Combine Smart and Joke into one smart joke
      </Sample>
    </Instruction>
  </OllamaProvider>
</AnthropicProvider>

Get started

Install script

Standalone binary, no runtime required.

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

Deno users

Run from source (a JSR package is coming soon).

git clone https://github.com/taras/executable.md
cd executable.md &amp;&amp; deno task xmd run doc.md

Prebuilt binary

Download for your platform from GitHub Releases.

xmd run path/to/doc.md