{"type":"blog","id":"2023/runme","title":"Making Markdown Interactive with Runme","url":"/blog/2023/runme","summary":"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?","date":"2023-12-22","tags":["Markdown","Interactivity"],"categories":["tech"],"body":"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?\n\nThat's what [runme][1], a CLI tool, VSCode extension, and online service promises to do.\n\n<!-- youtube:9PMu3i4-RFk -->\n\n## Example project\n\nFor this post, I use a repository read me generated by Docusaurus. Most of the code blocks are yarn commands.\n\n## Installation\n\nWhile it works best running inside [the VSCode extension][2] (which also contains the CLI binary), [you can install runme separately][3], or [run it with Docker][4]. 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.\n\n## CLI usage\n\nBy 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.\n\nThen, the code runs in the terminal as normal.\n\n![runme running in CLI](https://miro.medium.com/v2/resize:fit:1400/format:webp/1*ckBshY-jGi5wwrQBOk7nVA.png)\n\nIf you want to use `runme` against markdown files not called _readme_, use the `--filename` argument.\n\nAnd that's the main usage for the CLI tool, [but there are other options available][5].\n\n## VSCode usage\n\nUsing runme through the CLI offers some convenience, but the tool comes into its own when you use the VSCode extension.\n\nWith 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.\n\n![runme in VSCode](https://miro.medium.com/v2/resize:fit:1400/format:webp/1*aPR50C7tbbPS160vogYUnA.png)\n\nEvery 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.\n\nI 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.\n\nThe 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.\n\n[There are a bunch of other features and settings][6] , 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.\n\n## Web\n\nSo far, the functionality provided by runme is interesting, but the web integration turns it into a team-wide collaborative knowledge base tool.\n\nFirst, 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][7]. This is still running locally, but you could use a tool such as [ngrok][8] to expose that locally running service.\n\n![codeserver running runme in the browser](https://miro.medium.com/v2/resize:fit:1400/format:webp/1*-DTrPBAXbgJUBo2cW0RheA.png)\n\nWhile 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.\n\n![runme commands shared to the web](https://miro.medium.com/v2/resize:fit:1400/format:webp/1*m42kZBxdjFjcrAByDXGB6A.png)\n\n## And there's more\n\nSome of the other miscellaneous but interesting features are the following:\n\n- [Running Github actions inside a markdown file][9], which, if you combine with other commands, you can start to make a markdown file a runbook repository.\n- [Running runme (!) in a Github action][10], 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.\n- [A browser extension][11] 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.\n\n## Up and running\n\nI 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.\n\n_What do you think? Have you tried runme or any tools like it? Let me know in the comments._\n\n[1]: https://runme.dev\n[2]: https://docs.runme.dev/install#runme-for-vs-code\n[3]: https://docs.runme.dev/install\n[4]: https://docs.runme.dev/install#runme-with-docker\n[5]: https://docs.runme.dev/getting-started/cli\n[6]: https://docs.runme.dev/getting-started/vs-code\n[7]: https://github.com/coder/code-server\n[8]: https://ngrok.com/\n[9]: https://docs.runme.dev/integrations/embed-github-action\n[10]: https://docs.runme.dev/integrations/github-actions-workflow\n[11]: https://docs.runme.dev/integrations/browser-extension","links":[],"fields":{}}