shelldoc 1.0: A Relaunch Wrapped Up

shelldoc 1.0.0 is out. After three release candidates over six weeks, the relaunch that began in February with version 0.90 reaches its conclusion. This post looks back at what was done and forward at what comes next.

What was the relaunch about?

shelldoc was originally written several years ago. Once it reached a stable state, development slowed down. The core idea is sound: run the shell commands in your Markdown documentation and verify they still produce the right output. The tool had accumulated some bit-rot, primarily it was not updated with the shift from go get to go install and used some outdated dependencies.

Taking it over again in 2026 meant first bringing it back to a trustworthy baseline. Version 0.90 did the unglamorous work: updated to Go 1.21, fixed accumulated known issues, added CI with GitHub Actions and visual test result reporting. It was ready to use, but not yet ready to call stable.

0.91 shifted to code quality: expanded test coverage across the CLI, tokenizer, and JUnit XML output, added godoc comments to all exported functions, and removed an incomplete regex-matching feature that had never been production-ready. The goal was a codebase that future contributors (and future me) would find comprehensible and safe to change.

0.92 added the features that real use-cases demand: a --timeout flag to prevent runaway commands from hanging CI, per-block timeout control via the shelldoctimeout attribute, a --dry-run mode to review what would execute before committing to it, and graceful CTRL-C handling that saves partial results instead of abandoning them.

1.0 concludes the relaunch with a stable final version and a new logo.

What does shelldoc actually do?

It tests this kind of thing:

$ echo Hello
Hello

Lines in a code block that begin with $ or > are treated as commands. The lines that follow are the expected output. shelldoc executes the commands and checks whether reality matches documentation. If they diverge, the test fails.

That is the entire model. No new file formats, no special markup beyond what you would write anyway to show users a command. Adopting shelldoc in CI means adding one line to your workflow:

shelldoc run README.md

It produces JUnit XML, so test results appear as a structured report in GitHub Actions or any compatible CI system. It uses the same visualisation developers already use for unit tests, applied to documentation.

Who should use it?

shelldoc fits any project where the answer to a support question is frequently “did you try following the README?” CLI tools are the obvious case, but the scope is wider: libraries with installation examples, platforms with onboarding tutorials, infrastructure projects with build or deployment instructions. If you have Markdown with shell commands, you have something shelldoc can test.

shelldoc is GPL/LGPL for its own components, but it only tests your documentation, it never becomes part of your project. Its license does not proliferate. That removes a common objection to adopting GPL-licensed tooling.

The installation is a single binary with no runtime dependencies:

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

No Go toolchain needed at test time. Build the binary once, install it in your CI container, and run it on every pull request.

What adoption would mean

The practical hope is simple: that projects with shell examples in their documentation start running shelldoc in CI, catch regressions they would otherwise have missed, and spend less time fielding support requests from users who followed instructions that quietly stopped working.

Beyond individual projects, shelldoc fits naturally into shared CI templates and reusable workflows, meaning the kind of infrastructure that larger open source foundations or developer platforms maintain for their hosted projects. A documentation test step is as routine as a unit test step; it just hasn’t been standard practice yet.

Contributions are also welcome. The codebase is clean, the test coverage is solid, and the architecture is simple enough to be legible. If you have a use case that shelldoc doesn’t cover, an issue or pull request is the right place to start.

What comes next

shelldoc is stable. There are no known issues as of the release of 1.0.0. The RC cadence is done. shelldoc now follows semantic versioning with on-demand releases: a bug fix produces a patch release; a new feature produces a minor release. There will be no scheduled releases, changes go out immediately when they are ready.

shelldoc is free and open source software, licensed under GPL v3 for the command-line tools and LGPL v3 for the reusable library components. The project lives at github.com/mirkoboehm/shelldoc.