Introducing Markdown Playgrounds - Powered by WebAssembly

Syrus Akbary

Syrus Akbary

In WAPM, we have been thinking about how we can enable live coding on the code snippets inside Markdown Readme files.

WAPM is the Package Manager for WebAssembly modules. It allows anyone to create, distribute, and use web assembly packages based on WebAssembly anywhere: from servers to browsers.

Until today, interacting with online code snippets was complicated. The overhead is very high for developers with limited experience in a new language or for languages that require complex toolchains like Zig or Clang.

But not any longer!

We have created an easy way to allow interaction with any code from markdown files using fully sandboxed WebAssembly WAPM packages.

Here's the demo!

You can also play with the demo online in wapm.io/python/python

How to create a playgrounds

To make the code snippets interactive in your .md files, you need to add YAML annotations to the file as described below and an extra tag in the code snippet.

First, you will need to include the playground annotation next to your language of choice. The annotation defines the string to run code, and it's saved in the $CODE environment variable.

---
playground:
  python:
    run: echo $CODE > example.py ; python -i example.py
---

The run field defines how the code inside the editor will be "run" in the shell.

Once that's added, you will need to add the playground tag next to the language for the code section: Instead of using python` we will use python playground`

For example, the README.md for Python can look like the following:

---
playground:
  python:
    run: echo $CODE > example.py ; python -i example.py
---

Here's the Playground:

```python playground
name = input("What's your name? ")
print(f"Hello, {name}!")
```

The above code snippet produces the Markdown file, and it renders in WAPM.io  like this:

WAPM Playground rendered

If you're familiar with Jupyter Notebooks, you might have noticed this concept is very similar. However, there is one exception; WebAssembly powers WAPM markdown playgrounds. It makes it possible to define how to run the code inside the playground, so it's way more pluggable and easy to use!

We can't wait to see what you will do with it!

Do you want to play with this? We have good news for you! It's already integrated it into the following packages for your use: