Introducing Docmd: Turn Markdown into Executable Command Docs
You know that feeling when you're staring at a README with a dozen code blocks, trying to copy-paste commands into your terminal, only to miss a backtick or forget a flag? Or worse, when you need to run a multi-step setup from a GitHub repo and have to manually type each line?
Docmd is a tool that lets you write Markdown files where code blocks are actually live, runnable commands. Think of it as Markdown that doubles as a scriptable CLI.
What It Does
Docmd parses Markdown files and extracts fenced code blocks (triple backticks) that contain shell commands, then lets you execute them directly from the terminal. You write normal Markdown documentation but annotate which blocks should be runnable. When you run docmd mydoc.md, it presents an interactive menu of those commands, allowing you to select and execute them one by one, or run them all in sequence.
Under the hood, it's a Go binary (so single, statically linked executable) that reads the Markdown AST, identifies runnable code blocks, and streams their output to your terminal. No YAML, no config files, no hidden scripts. Just your documentation, made executable.
Why It’s Cool
Markdown is already the standard. Every dev knows how to write it. Docmd doesn't ask you to learn a new format, and it doesn't require you to maintain a separate run.sh alongside your docs. You just add a tiny annotation to your code blocks.
No lock-in. Your Markdown files work in any viewer, editor, or renderer. Docmd only cares about blocks tagged with a special language identifier (like bash docmd). The file remains fully readable on GitHub, VS Code, or plain text.
Great for onboarding. Imagine a README with a "Quick Start" section where every command can be run with a single keystroke. New contributors or team members can set up the project without alt-tabbing between the browser and terminal.
CI-friendly. You can also use Docmd to automatically verify that your documentation's commands still work. It's a poor man's integration test for your docs.
How to Try It
Install Docmd (macOS/Linux via Homebrew or download the binary from releases):
brew install docmd-io/tap/docmdOr grab the latest binary from the releases page.
Create a Markdown file with a