xmd

xmd (Executable Markdown) is a Rust CLI that renders any text file by replacing embedded shell command blocks with their stdout.

The file extension is ignored. .md, .mdc, .mdx, .txt, or any other text file all work the same way.

Install

npm (recommended)

npm install -g @nothumanwork/xmd
xmd --help

Or run once without a global install:

npx @nothumanwork/xmd examples/sample.md

From source

Requires Rust 1.85 or newer.

cargo build --release
./target/release/xmd examples/sample.md

Syntax

The renderer recognizes a single template form:

{{! ... !}}

Everything between {{! and !}} is treated as one shell script.

Inline example:

Current branch: {{! git branch --show-current !}}

Multiline example:

{{!
printf 'one\n'
printf 'two\n'
printf 'three\n'
!}}

Behavior

• Every command block is executed independently.
• Command blocks are executed in parallel.
• Replacement order is deterministic and follows the source document order.
• On Unix-like systems commands run via /bin/sh -c.
• On Windows commands run via cmd.exe /C.
• Commands run relative to the input file's parent directory.
• Only stdout is injected back into the template.
• If any command exits non-zero or cannot be started, rendering fails and diagnostics are written to stderr.

Usage

xmd [options] <file>

Options:

• --max-parallel <n>: maximum concurrent commands (default: number of CPUs)
• --max-output-bytes <n>: per-command stdout/stderr capture cap
• -h, --help: show usage
• -V, --version: show version

Examples

cargo run -- examples/sample.md
./target/release/xmd examples/sample.md
xmd --max-parallel 4 notes.txt

Example template

# Greeting

{{! printf 'hello from xmd\n' !}}

# Numbers

{{!
printf '1\n'
printf '2\n'
printf '3\n'
!}}

Rendered output:

# Greeting

hello from xmd

# Numbers

1
2
3

Development

cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets
cargo llvm-cov --fail-under-lines 90
cargo bench --bench render_parallel

npm publishing

This repo publishes @nothumanwork/xmd with platform-specific optional dependencies via cargo-npm.

Platform packages (one binary each):

• @nothumanwork/xmd-linux-x64
• @nothumanwork/xmd-linux-arm64
• @nothumanwork/xmd-darwin-x64
• @nothumanwork/xmd-darwin-arm64
• @nothumanwork/xmd-win32-x64
• @nothumanwork/xmd-win32-arm64

Release steps:

1. Set repository secret NPM_TOKEN with publish rights to @nothumanwork.
2. Bump version in Cargo.toml and commit.
3. Push a matching version tag: git tag v0.2.1 && git push origin v0.2.1.
4. The Release npm workflow builds binaries for Linux, macOS, and Windows (x64 + arm64), stages them for cargo-npm, and verifies every generated package.
5. The workflow publishes and verifies every platform package before it publishes the main package. Verification retries until npm shows each new version, then the main package publishes. A repeated run skips versions that already exist, so it can recover from a partial release.

Do not publish or change the generated main package by hand. Its version and all optionalDependencies must match Cargo.toml. The main package does not publish until every platform package exists on npm at that exact version. Versions 0.1.0 and 0.2.0 of the main package point at missing platform packages; use 0.2.1 or newer.

Local dry-run after building every configured target:

cargo build --release --target x86_64-unknown-linux-gnu
cargo npm generate --clean --out-dir npm
node scripts/verify-npm-packages.mjs npm
node npm/@nothumanwork/xmd/bin/xmd.js --version
# Requires NPM_TOKEN and all configured target binaries before a real publish:
# cargo npm publish --out-dir npm -- --access public --dry-run

Project layout

• src/main.rs: CLI entry point
• src/cli.rs: argument parsing and help text
• src/app.rs: orchestration of parse → execute → render
• src/template.rs: parsing {{! ... !}} blocks and rebuilding the document
• src/runner/: parallel command execution and diagnostics
• tests/: end-to-end CLI tests
• benches/: Criterion benchmarks for parallel shell rendering
• docs/: GitHub Pages site
• adr/: architecture decision records (ASD-STE100)
• AGENTS.md: agent-facing maintenance notes
• .cursor/rules/xmd.mdc: Cursor rules for agents

Documentation site

User documentation lives in docs/ and deploys to GitHub Pages through .github/workflows/pages.yml.

Notes for coding agents

This repository includes:

• AGENTS.md for shared maintenance guidance
• .cursor/rules/xmd.mdc for Cursor agent rules
• CLAUDE.md which imports AGENTS.md for Claude Code compatibility
• a project skill at .claude/skills/xmd-maintainer/
• ADRs under adr/