shelldoc

Documentation drift is ubiquitous: READMEs with curl commands that 404, install instructions for deprecated flags, build steps that assume a directory structure that changed six months ago. Most projects don’t catch this until a frustrated user opens an issue.

shelldoc addresses this by testing Unix shell commands embedded in Markdown files. It parses code blocks, executes the commands, and verifies that the output matches documented expectations. The clever part: instead of requiring a new documentation format or restructuring anything, it just runs what’s already there. Adopting it only requires adding a line like shelldoc run documentation.md to your CI configuration.

Quick example

A code block in your README like this:

$ echo Hello
Hello

tells shelldoc to run echo Hello and verify the output is Hello. If they don’t match, the test fails. At most minor modifications to the Markdown file, no special markup, just the commands you’d show users anyway.

shelldoc can check for expected command exit codes, expected output, or command timeouts.

Installation

go install github.com/mirkoboehm/shelldoc/cmd/shelldoc@latest

Why shelldoc?

• Language-agnostic: While shelldoc is written in Go, it works with any Markdown documentation. It tests shell commands, not language-specific code, making it useful for projects in any language.
• Zero dependencies: Install with go install and get a single, self-contained binary. No runtime dependencies required.
• CI-friendly: Install the shelldoc binary at container build time. No Go toolchain needed when running your tests. The binary is statically linked and comes with no additional dependencies.
• License-safe: shelldoc only tests your documentation; it doesn’t become part of your project. Its license never proliferates to your code.
• Practical defaults: Command timeouts prevent runaway processes from hanging your CI. Dry-run mode lets you preview what would execute. CTRL-C cleanly terminates test runs.

Where it shines

shelldoc works well for CLI tools and libraries with install or usage examples, projects with build instructions, and tutorials that walk through shell interactions. Use it on any repo where “did you try the README?” is a common support response.

A lot of technical writing boils down to “run this, see that”. That’s exactly what shelldoc verifies. It produces JUnit XML output for CI integration.

Release history

Version 1.0.0 was released on 19 March 2026. Going forward, shelldoc follows semantic versioning: every bug fix triggers a patch release, every new feature a minor release.

I relaunched shelldoc in 2026 after a maintenance hiatus. Version 0.90 was the first of three release candidates, featuring bug fixes, security improvements, modernization to Go 1.21, and GitHub Actions CI with visual test reports.

The shelldoc project is hosted on GitHub. Contributions are welcome.