shelldoc 0.90: Testing Shell Commands in Markdown Documentation

I am happy to announce the relaunch of shelldoc with version 0.90. After a maintenance hiatus, I have taken over active maintenance of shelldoc again in 2026. This release marks the first of three planned release candidates on the road to a stable 1.0 version.

What is shelldoc?

shelldoc tests Unix shell commands embedded in Markdown documentation. It parses Markdown files, identifies code blocks containing shell commands, executes them, and verifies that the output matches the documented expectations. This ensures that your documentation examples remain accurate and up-to-date as your software evolves.

Consider a simple example in your README:

$ echo Hello
Hello

shelldoc will execute echo Hello and verify that the output matches “Hello”. If documentation and reality drift apart, shelldoc will catch it.

Why does this matter?

Documentation rot is a common problem in software projects. Examples that worked when written become outdated as APIs change, dependencies evolve, or behavior is modified. Users following outdated instructions encounter errors, leading to frustration and support burden.

By integrating shelldoc into your CI pipeline, every pull request automatically validates that documented shell commands still work as described. The tool produces JUnit XML output that integrates with common CI systems, providing visual test reports for documentation accuracy.

What’s new in 0.90?

This release focuses on modernization and stability:

• Bug fixes and security improvements addressing issues accumulated during the maintenance hiatus
• Modernized to Go 1.21 with updated dependencies
• GitHub Actions CI with visual test result reports
• Improved documentation including security considerations and limitations

Installation

Installing shelldoc is straightforward with Go:

go install github.com/mirkoboehm/shelldoc/cmd/shelldoc@v0.90

Road to 1.0

Version 0.90 is the first of three release candidates planned before the stable 1.0 release. I plan bi-weekly releases until stable, incorporating feedback and addressing issues discovered during testing.

Testing and experimentation are encouraged. If you maintain documentation with shell examples, I would appreciate feedback on how shelldoc works for your use case. Contributions and pull requests are welcome at the GitHub repository.

shelldoc is free and open source software, licensed under GPL v3 for the command-line tools and LGPL v3 for the reusable library components.