Markdown Task Runner
mx is a task runner that executes code blocks in Markdown files based on section titles.
It is implemented using mq, a jq-like command-line tool for Markdown processing, to parse and extract sections from Markdown documents.
Warning
mx is currently under active development.
- Execute code blocks from specific sections in Markdown files
- Configurable runtimes for different programming languages
- Support for custom heading levels
- TOML-based configuration
- Built on top of the mq query language
curl -sSL https://raw.githubusercontent.com/harehare/mx/refs/heads/main/bin/install.sh | bashThe installer will:
- Download the latest mq binary for your platform
- Install it to
~/.mx/bin/ - Update your shell profile to add mq to your PATH
$ cargo install --git https://github.com/harehare/mx.git# Run from README.md (default)
mx "Task Name"
# Run from a specific file
mx -f tasks.md "Task Name"mx run "Task Name"
mx run --file tasks.md "Task Name"You can pass arguments to your task using -- separator:
# Pass arguments to a task
mx "Task Name" -- arg1 arg2 arg3
# With explicit run command
mx run "Task Name" -- arg1 arg2 arg3
# From a specific file
mx -f tasks.md "Task Name" -- arg1 arg2Arguments are accessible via environment variables:
MX_ARGS: All arguments joined by space (e.g., "arg1 arg2 arg3")MX_ARG_0,MX_ARG_1, ...: Individual arguments
Example in a Markdown task:
## My Task
```bash
echo "All args: $MX_ARGS"
echo "First arg: $MX_ARG_0"
echo "Second arg: $MX_ARG_1"
```# List tasks from README.md (default)
mx
# List tasks from a specific file
mx -f tasks.md
mx list --file tasks.mdmx initThis creates an mx.toml file with default runtime settings.
Create an mx.toml file to customize runtime behavior:
# Heading level for sections (default: 2, i.e., ## headings)
heading_level = 2
# Runtimes configuration
# Simple format: language = "command"
# The execution mode defaults to "stdin"
[runtimes]
bash = "bash"
sh = "sh"
python = "python3"
ruby = "ruby"
node = "node"
javascript = "node"
js = "node"
php = "php"
perl = "perl"
jq = "jq"
# Detailed format with execution mode
# Execution modes: "stdin" (default), "file", or "arg"
# - stdin: Pass code via standard input
# - file: Write code to a temporary file and pass it as an argument
# - arg: Pass code as a command-line argument
[runtimes.go]
command = "go run"
execution_mode = "file" # Go requires file-based execution
[runtimes.golang]
command = "go run"
execution_mode = "file"
[runtimes.mq]
command = "mq"
execution_mode = "arg" # mq uses query as argumentYou can also mix both formats:
[runtimes]
python = "python3" # Simple format, uses default stdin mode
[runtimes.go] # Detailed format with custom execution mode
command = "go run"
execution_mode = "file"# Using shorthand (from tasks.md by default)
mx Build
# From a specific file
mx -f tasks.md Build
# Using explicit run command
mx run Build
mx run --file tasks.md BuildMIT