We’re excited to announce the release of tesh – a new open source tool for creating testable shell sessions in Markdown.
At its core, tesh is a simple but powerful tool that makes it easy to create and run shell sessions within Markdown documents. This is incredibly useful for teaching and explaining how to use a particular tool or command-line interface, as it allows you to show your audience exactly what they need to do in order to get started.
One of the biggest challenges when it comes to teaching and explaining shell interactions is making sure that the examples you provide are still accurate and relevant over time. With tesh, this is no longer a problem: tesh automatically runs the commands and verifies their output when the documentation is built. As such, you can be sure that the examples you provide are always up-to-date and accurate.
tesh is built using Python, and it’s easy to get started. Simply install tesh using pip, and then you can start verifying shell sessions in your Markdown documentation with the tesh README.md command.
The sessions are defined using a simple, easy-to-read syntax, making it easy to write, read and understand. All you need to do, is append tesh-session="<name>" to your existing code blocks.
```console tesh-session="hello"
$ echo "Hello World!"
Hello World!
```The main design decision of tesh is that it doesn’t introduce any new syntax or characters to the shell session code blocks. This is an important consideration, as some other tools in the market do this, which can be confusing for readers of your documentation. When readers see strange characters in the presented output, they may wonder what they mean and how they should interpret them. With tesh, the output is exactly what you would see if you were to run the commands in your own shell, making it easy for readers to understand and follow along.
This not only makes tesh easy to use, but also makes the documentation clear and easy to understand, so the readers can focus on learning the concepts rather than trying to interpret the output. We believe that this is a key feature that sets tesh apart from existing similar tools and was one of the main reasons why we decided to write tesh.
Check out the project’s GitHub page at https://github.com/oceansprint/tesh, and if you have any question or feedback, don’t hesitate to reach out.
