Post Runnable Code Snippets

Help Your Readers Learn Faster

24 Nov 2018 - Mohamed El-Geish

Learning how to code or to grasp a new programming concept is no walk in the park. Practice is very much needed just like when learning how to swim or to fly a plane. The sooner practice follows the acquisition of knowledge, the stronger that nugget of knowledge cements.

That’s not normally the case with posts with code: Authors may include code samples of interconnected, complex concepts and expect readers to follow that with practice on their own. However, readers may face hurdles like unclear prerequisites, conflicting dependencies, unsupported operating systems or hardware, etc.

One solution that comes in handy is Docker images: Authors can provide images that take care of the complicated setup; readers, in turn, simply need to run them using a single Docker command. That said, getting started with Docker can be a challenge for some readers depending on their experience level. The better solution is to run the code where it’s being read — in the post itself. Luckily, this is possible today thanks to web IDEs and online code playgrounds platforms like Tech.io, which offers this service (and more) for free.

Using Tech.io, you may write code in almost any programming language of your choice using a sophisticated web IDE and then use an iframe or Embed.ly, which means you may use it on Medium and other platforms, to embed code snippets in your posts. Readers can view your code snippets in Tech.io’s embedded web IDE, which supports syntax highlighting, autocomplete, folding uninteresting lines, and — more importantly — editing! Readers can tweak the code and run their own version or revert back to your version with a click of a button. Here’s an example:

Tech.io furnishes a slew of features; some are more advanced than others. The below is a quick guide of when and how to use them:

For a single-file example written in a programming language that’s supported out of the box, and with no dependecies required, a snippet is sufficient.
For code examples that require multiple files, you have to create a playground. You’ll also need to configure a project to associate with the example; here’s how to link code files to a project:
```
@[Compile]({"project": "LearnC++", "stubs": ["foo.cpp", "compile.sh"], "command": "bash compile.sh"})
```
A project needs a runner, which is a Docker image used to run the project and the code examples linked to it. Here’s how to configure a project in techio.yml:
```
projects:
  LearnC++:
      root: /projects/some-folder
      runner: techio/cmake-gcc-runner:latest
```
Tech.io created a list of runners that may be used out of the box.

For code snippets that require additional — yet lightweight — setup, you may configure a buildCommand to perform install actions:

projects:
  LearnC++:
      root: /projects/some-folder
      runner: techio/cmake-gcc-runner:latest
      buildCommand: cd /foo/bar && ./setup.sh

For unsupported programming languages and/or code snippets that require involved setup, you may supply your own Docker image as a custom runner:
```
projects:
  powershell:
      root: /projects/powershell
      runner: computingwithdata/powershell:latest
```
For snippets that produce graphical output (that can be viewed in a browser), you may want to produce the output (e.g., a PDF file) then print out the following to stdout:
```
TECHIO> open -s /project/target/ output.pdf
```

Here’s an example that displays a 3D surface plot:

We used Tech.io to build a playground with 300 lessons for the material of Computing with Data; the playground’s config can be found here.

Happy coding!