shelldoc

Markdown is widely used for documentation and README files that explain how to use or build software. Such documentation often contains shell commands demonstrating how to build or run it. To ensure documentation remains accurate and up-to-date, it should be automatically tested. shelldoc tests Unix shell commands in Markdown files and reports the results.

shelldoc parses Markdown files, identifies code blocks containing shell commands, executes them, and verifies that the output matches the documented expectations. It produces JUnit XML output for CI integration.

I relaunched shelldoc in 2026 after a maintenance hiatus. Version 0.90 is the first of three release candidates on the road to 1.0, 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.