Making Markdown Interactive with Runme
Markdown may be popular for its simplicity and “plainness”, but it’s often full of information. Whether for internal or external consumption, that information often contains code snippets for running certain commands or code examples. Wouldn’t it be great if you could run that code directly as you read from within the markdown?
That’s what runme, a CLI tool, VSCode extension, and online service promises to do.
Video version
Example project
For this post, I use a repository read me generated by Docusaurus. Most of the code blocks are yarn commands.
Installation
While it works best running inside the VSCode extension (which also contains the CLI binary), you can install runme separately, or run it with Docker. However, if you install with the VSCode extension, you can’t use the runme command from CLI, so weigh up how you intend to use it.
CLI usage
By default, if you run the runme command in a folder with a readme.md file, then it scans the file for code blocks marked as shell or bash and presents them in a command line user interface (CUI) for you to select the code to run.
Then, the code runs in the terminal as normal.
If you want to use runme against markdown files not called readme, use the --filename argument.
And that’s the main usage for the CLI tool, but there are other options available.
VSCode usage
Using runme through the CLI offers some convenience, but the tool comes into its own when you use the VSCode extension.
With the extension, any markdown files you now have open look different, and not just readme files, as the plugin overrides the default markdown editor view. It adds a couple of different components.
Every code block now is now in a cell with a “run” or a “cli” button, depending on if you’re in preview or edit view. Click that button, and the code example runs inline in VSCode. Unfortunately, it marks all code blocks as runnable, but it only works with bash or shell. There might be a setting to disable that. Runme does a good job of detecting how to run the command, but it doesn’t always get it right, and you can manually override its assumptions by clicking the language selector button.
I also found a few occasions when runme or VScode (it’s hard to say) couldn’t find the command in my environment. I spoke with the runme developers, and they are aware of the issue, but it’s sometimes hard to track down, and the runme extension isn’t the only extension I’ve encountered issues with.
The plugin also turns all non-code markdown into blocks and renders them in a preview you can click into to edit. You can also drag and drop these cells around the page in a WYSIWYG manner.
There are a bunch of other features and settings , and if you’re uncertain if you want the extension to do any more than allow you to run code blocks, then you can toggle and configure many of the features.
Web
So far, the functionality provided by runme is interesting, but the web integration turns it into a team-wide collaborative knowledge base tool.
First, if you installed it with the CLI tool, you can run runme open to start a browser-based version of VSCode that uses code-server. This is still running locally, but you could use a tool such as ngrok to expose that locally running service.
While in its early days, runme has the beginnings of a hosted platform in which you can share commands and outputs between team members, and even since I created the video version of this post, the team have added an ability to see all markdown files in a GitHub organisation and run commands from the browser.
And there’s more
Some of the other miscellaneous but interesting features are the following:
- Running Github actions inside a markdown file, which, if you combine with other commands, you can start to make a markdown file a runbook repository.
- Running runme (!) in a Github action, initially, I was confused as to the use of this, but it means you can test the code in markdown files with one tool, which is actually immensely useful.
- A browser extension for running commands in markdown files stored in GitHub repositories. Again, this is cool for quickly testing projects without installing anything first. But I’m not sure where the commands run, and I imagine there are a few limitations on what can run in the browser.
Up and running
I have always been a fan of interactive documentation, and while runme only supports shell commands and is primarily aimed at working inside some form of code editor at the moment, I see it developing in a broader direction. Runme is in its early days and has a lot of other small features that may add up to a cohesive product offering over time.
What do you think? Have you tried runme or any tools like it? Let me know in the comments.
If you like what you're reading, support my work
Start learning something new or up-skilling with a book or course.
30% off ANYTHING at Manning
Simple and clear, but packed with features, Simple Screenshot is a drop in replacement for macOS.
Get Simple Screenshot