Markdown Runbook Automation: Why It Wins

When evaluating runbook automation tools, you’ll find two camps: proprietary workflow engines with visual builders, and simple tools that treat runbooks as plain text.

We believe plain text wins. Here’s why Markdown-based runbook automation is the right choice for most teams.

The Problem with Proprietary Formats

Many runbook automation tools use custom formats:

• Visual workflow builders
• YAML-based DSLs
• Proprietary JSON schemas
• Database-stored procedures

These approaches create problems:

Vendor Lock-In

Your runbooks become trapped. Moving to a different tool means rewriting everything. The more runbooks you create, the harder it is to leave.

Learning Curve

Every new hire must learn the tool’s specific format. Instead of writing documentation, they’re learning a proprietary system.

Version Control Friction

Binary formats and database-stored procedures don’t diff well. Code review becomes difficult. Change history is opaque.

Collaboration Barriers

Not everyone has access to the tool. Runbooks become siloed in a platform that requires licenses, training, and specific access.

Why Markdown Works

Markdown solves these problems elegantly:

Universal Format

Every developer knows Markdown. No training required. New team members contribute on day one.

Git-Native

Markdown files work perfectly with Git:

git diff runbooks/restart-api.md

You see exactly what changed, who changed it, and when.

Tool Agnostic

Markdown runbooks work with any runbook automation tool that supports the format. Switch tools without rewriting content.

Readable Everywhere

No special software required to read a Markdown file. GitHub renders it. VS Code renders it. Even cat works in a pinch.

Executable Markdown

The magic happens when Markdown becomes executable. A runbook automation tool that understands Markdown can:

Parse Code Blocks

```bash
kubectl get pods -n production
```

The tool knows this is a command that can be executed.

Handle Variables

Set the namespace:

​```bash
export NAMESPACE=production
​```

Then use it:

​```bash
kubectl get pods -n $NAMESPACE
​```

Variables persist across blocks, just like a real terminal.

Support Multiple Languages

```bash
# Shell commands
kubectl get pods
```

```python
# Python scripts
import requests
response = requests.get("https://api.example.com/health")
print(response.json())
```

The tool executes each block with the appropriate interpreter.

Structuring Markdown Runbooks

Good Markdown runbooks follow patterns:

Use Headings for Sections

# API Service Recovery

## Prerequisites
- Access to production cluster
- kubectl configured

## Diagnosis
[diagnostic commands]

## Remediation
[fix commands]

## Verification
[validation commands]

Include Context

## Check Pod Status

This shows all API pods and their current state. 
Look for pods in CrashLoopBackOff or Error states.

​```bash
kubectl get pods -n production -l app=api
​```

Commands with context are more useful than raw commands.

Add Decision Points

## Is the Database Healthy?

​```bash
pg_isready -h db.example.com -p 5432
​```

**If connection fails:** See [Database Recovery Runbook](./database-recovery.md)

**If connection succeeds:** Continue to next section

Link Related Runbooks

## Related Runbooks

- [Database Recovery](./database-recovery.md)
- [Cache Flush](./cache-flush.md)
- [Full Service Restart](./full-restart.md)

Markdown + Git = Runbook as Code

The combination is powerful:

Pull Request Workflow

git checkout -b update-api-runbook
# Edit runbook
git add runbooks/api-recovery.md
git commit -m "Update API recovery for new namespace"
git push origin update-api-runbook
# Open PR for review

Runbook changes get the same review as code changes.

Automated Testing

CI can validate runbooks:

• Lint Markdown syntax
• Check for broken links
• Validate command syntax
• Run against staging

Change History

git log --oneline runbooks/api-recovery.md

Full audit trail of every runbook change.

Stew: Executable Markdown for Ops

Stew is a runbook automation tool built on these principles:

• Markdown-native — Your runbooks are plain .md files
• Git-friendly — Store runbooks with your code
• Zero lock-in — Switch tools anytime, keep your runbooks
• Instantly executable — Run commands directly from Markdown

Join the waitlist and see why plain text runbook automation just works.