Run your README.md in VS Code like a notebook

In our continued efforts to make documentation more reliable and less vulnerable to bit-rot, we released runme CLI (it has been renamed rdme) back in August. The CLI lets you easily execute shell blocks inside you README.md document from terminal. We were pleasantly surprised how well it was received. Thank you all for the comments and feedback!

Zero-changes are required to turn your README.md into a playable notebook

Today we want to take Runme a step further and break out of Terminal’s trust. One of the more notable comments in response to the anecdotal (yet not the only persuasive) runme CLI (it has been renamed rdme) this was it:

Install Runme or Search from VS Code Marketplace runme inside extension panel

Notable response to Runme's CLI

Nice thing! We wholeheartedly agree that it is important Reading Yours README.md before this run The command it describes. With today’s RunMe release, it just got a lot easier:

really execute your [README.md](http://README.md) by simply clicking the play button

Truly execute your README.md by simply clicking on the play button

We wanted to expand beyond Runme’s CLI implementation:

  1. Enable contributors to both learn about and interact with documents
  2. Empower maintainers to control and curate developer performance experience
  3. Encourage contributors to make suggestions about the Readme experience

We took a good look around and found inspiration in the data science community: DS love Jupyter Notebooks! Notebooks dynamically intertwine code, calculations, numbers and narrative, where scientists create notebooks that can be used seamlessly.

Long clip and introduction available here [https://www.codecademy.com/article/introducing-jupyter-notebook](https://www.codecademy.com/article/introducing-jupyter-notebook)

Long clip at https://www.codecademy.com/article/introducing-jupyter-notebook

A notebook with the built-in ability to recalculate (literally run) each paragraph (input and output cells) in a low-code fashion, naturally aids the reader in understanding of the information laid before them. This enables improvements to notebooks to be easily upstreamed using pull requests as notebooks reside in a version-tracked repo.

Bingo! It turns out that repo maintainers and contributors have a similar relationship to the DS community when it comes to technical documentation.

After a fair amount of experimentation, we decided to build a VS Code extension UX on top of Runme Parser. This extension will now make your README.md (onboarding and runbook docs) available within the VS Code powered notebook experience, with zero changes to the underlying markdown required. To show an end-to-end example, we created a repo https://github.com/stateful/runme.dev (support https://runme.dev) using Deno’s FreshWeb Framework, a CMS, test, ) has been collected. and deployment. here is my:

Install Runme or Search from VS Code Marketplace runme inside extension panel

performance control and more

Runme transparently parses the README.md files into its component sequences (arbitrary Markdown) and executable blocks (such as shells) that describe your apps and services.

Taking advantage of VS Code’s Notebook API (which underpins notebook rendering), runme displays your README.md (or any other markdown file) as input and output cells in a notebook.

Skip tedious copy and paste with notebook-style run controls

Skip tedious copy and paste with notebook-style run controls

These notebook entries enable:

  1. execution control per block
  2. Shell support and terminal integration
  3. Basic ENV support in notebook cell

Curate Your Notebook Experience

Attributes let maintainers control various aspects of the developer experience through simple annotations (full list available here) inside the code blocks of your README. Ordinary markdown viewers will ignore them. Sharing and merging across notebook changes is just a git clone, git push or pull request away.

Annotate your fence code blocks to curate your shell execution

Annotate your fence code blocks to curate your shell execution

Beyond Shell and Terminal

We chose to first unlock shell execution in runme notebooks to provide wider compatibility with existing readme and their potential use of CLI tooling. However, as Jupyter has first-class integration with plotting libraries and other rich visual renderers, we saw an opportunity to enrich UX by going beyond text representation and bringing in richer web experiences.

To show you how this would work, we started with our friends at Deno:

Preview and deploy to production easily

Deploy both preview and production Deno with ease

We’re envisioning a world where instead of logging into a scattered cloud web console (provided by service providers), you can drop a web component into a cell that uses their APIs inside your RunMe notebook. Exposes programmable UX for different parts. We believe this approach has great potential to lead to a more concise and maintainable way to document full stack applications and services.

what do you think

Interoperability with CLI

While we believe that Runme Notebooks will provide a better onboarding experience for new contributors, we understand that maintainers and power contributors may skip moving. The same is true for execution inside CI/CD, which is why we designed runme to function headless. runme CLI.

Interoperability with CLI

Interoperability with CLI

We are still experimenting with UX and deciding where to draw runmeworking to achieve broader interoperability (eg handling ENV volumes in the CLI). One of our goals is to maintain a symbiosis between the CLI and notebook implementations to achieve the best possible developer experience for reliably runnable documentation.

Install Runme or Search from VS Code Marketplace runme inside extension panel

We chose to release Runme early as an invitation to the dev community to participate in its ongoing development. Both the extension and the CLI are still under heavy development and have not yet undergone extensive battle testing. If anything comes your way please send us bug reports and feature requests.

Here are some known limitations you should be aware of in this alpha release:

  • Notebooks are currently read-only, to modify your notebook please edit the built-in Markdown/README.md as a text file. We want to fully support bidirectional editing in the future.
  • Be careful with environment variables interleaved within code blocks. Stateful execution of notebooks (shell/bash-only; no PowerShell on Windows yet) takes advantage of a naive implementation where the VS Code extension prompts for ENV var values ​​and tries to expand them. In short, it doesn’t correspond to an interactive bash/shell session (yet).
  • We continue to experiment with aspects of the user/developer experience, including passing information/variables from cell to cell, ENV version handling that more closely matches a session, and more robust markdown handling.

Come find us and talk about Runme (here’s my email or join the feud), we’re excited to hear your thoughts!

Thanks.

Leave a Comment