brain

Markdown runbooks

Properties7
statusseedling
typeconcept
created2026-09-23
updated2026-09-23
tagsmarkdown, devops, documentation, runbooks, tools-for-thought
aliasesRunnable markdown
public

3 min read

Markdown runbooks

Runnable markdown: fenced code blocks in an ordinary document become executable tasks — commands run in a real terminal with their output kept beside the instructions that call for them. The document stops being a description of a procedure and becomes the procedure: README.md and the on-call runbook turn from prose that bitrots into steps you actually execute, verify, and hand off. It is one more entry in the Markdown won column — the format is already where docs live, so execution is added on top rather than migrated to.

The pattern exists because the problem is old: operational docs drift from reality because nothing forces them to stay true. A runnable doc is tested every time it is used — a broken command fails at run time instead of misleading a reader at 3 AM. Much of this converges on the Jupyter metaphor (code cells + outputs + narrative) rebuilt terminal-first, without the notebook file format.

The field (as of 2026-09-23)

  • runme (OSS) — Go CLI + VS Code extension by Stateful/runmedev (2022, Apache-2.0, 2,174★, actively pushed). Runs fenced blocks as terminal sessions, polyglot runtimes via shebang, cell-level env retention, “Run with Runme” badges. The most popular and most mature of the field — my prior default consideration.
  • upmd (OSS) — Rust/ratatui TUI by rezigned (2026-07, MIT, 196★, zero open issues). Blocks as named tasks with a dependency graph → workflows; each task gets a real PTY (prompts, colors, editors, pagers); TUI / one-shot CLI / CI modes; output beside source; env + working-directory changes propagate to later tasks. Terminal Trove Tool of the Week (2026-09-22).
  • runbooks (OSS) — Gruntwork’s Electron desktop rendering MDX with React execution components (scripts, AWS/GitHub auth flows, repo cloning, file templates). Heavier, opinionated toward infra-expert capture; single-author, 30★, MPL-2.0; security model explicitly documented (executable registry, sandboxed renderer, but “only open Runbooks you trust” — arbitrary code by design).

Adjacent but different: Jupyter (notebook-first, kernel-based), Quarto (publishing, not execution-in-place), Makefile/just (task runners without the document), Diátaxis (runbooks as a docs genre, no execution). In each case markdown-native execution-in-place stays the differentiator here.

Fit

For homelab/ops use the CLI/TUI tools fit the existing workflow best: docs already live in git as markdown (AGENTS.md, READMEs, _specs/), and a runnable block closes the loop between documented and actual state. runme is the safe pick (maturity, ecosystem, VS Code); upmd is the interesting one (dependency graph between blocks, PTY fidelity, ratatui TUI — very aligned with the CLI all the things instinct) but is two months old. Gruntwork Runbooks’ Electron+MDX model is a different beast — desktop app, not a terminal tool.

Graph View

Backlinks