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

1. Install Docmd (macOS/Linux via Homebrew or download the binary from releases):

   brew install docmd-io/tap/docmd
   

   Or grab the latest binary from the releases page.

2. Create a Markdown file with a runnable code block. Use bash docmd as the language identifier:

   # Hello Docmd
   
   Run this:
   
   ```bash docmd
   echo "Hello, world!"
   ```
   

3. Run it:

   docmd hello.md
   

   You'll see an interactive prompt. Press enter to execute the command, or type run all to execute everything in order.

That's it. No setup, no config.

Final Thoughts

Docmd feels like one of those tools you didn't know you needed until you try it. It's simple, well scoped, and doesn't try to solve every problem. I like that it leans into Markdown's existing strengths rather than reinventing the wheel.

If you write documentation for CLI tools, dev environments, or CI setups, this could save you and your users a lot of copy-pasting. Give it a shot on your next README or project setup guide.

Follow us at @githubprojects for more dev tools.