Interactive Notebooks - Part 1: Getting Started with nteract

In this two-part post, I explain what are interactive notebooks, why we’d want to use them, and how to get started with the nteract desktop program.

My Life Before Interactive Notebooks

A lot of the writing that I do has code mixed in with the text. Because of this, I’ve come to love writing my documents in Markdown. I especially appreciate being able to take advantage of “fenced” code blocks so that my code is just as legible while I’m writing as it is in the finished product.

Here’s what a fenced code block looks like in raw markdown

```javascript
function sum() {
  return 4 + 3 + 2 + 1;
}
console.log(sum());
```

And here’s what that block will look like when it’s rendered by the Markdown parser.

function sum() {
  return 4 + 3 + 2 + 1;
}
console.log(sum());

The code is displayed in a fixed width font, and many Markdown applications will also highlight the language’s syntax.

I recently discovered an even more awesome way to work with code while I’m writing.

Let’s say that I wanted to show the results of running the ruby code in my example above. The way I’d typically do that from my favorite Markdown editor is to copy and paste the code into a new file (or into a REPL). That would generate some output for me, and then I’d copy that output and paste it back into my original document.

I’ve run into some issues with that in the past:

• On occasion, I became lazy

  I don’t always actually run the code that I’ve written. A bunch of times, I’ve written out what I’m 90% sure that the code will generate. This has caused problems before. A stray character can leak in and, then, the code doesn’t work. If I publish my result, then the people who copy and paste my code will be the first ones to try and run it, and also be the first ones who’ll notice a problem.

• Things changed

  I’ll often write the original block of code in my text editor. Later, when I copy it elsewhere, I may notice that it needs changes. I’ll make those changes and get things running correctly. But I sometimes forget to copy the result back into my text editor.

• I forgot

  There have also been times when I just forgot to copy the output into my Markdown document.

• Formatting got lost

  Sometimes, the code that I run generates a nice output which might include colors. Those colors are hard to copy back. When I find that I want to copy the colors back, I typically end up taking a screenshot and putting that in my document. Taking screenshots of text just seems like a waste, though. A search engine is going to have a hard time indexing the text content embedded in my screenshot. So if there’s a keyword in there which might help someone find the content later, it gets lost.

Enter the Interactive Notebook

So what would the above example look like in an interactive notebook? Let’s take a peek.

function sum() {
  return 4 + 3 + 2 + 1;
}
console.log(sum());

10

Nice! We have the code in a syntax highlighted block and, right below that, we have the output that was generated at the moment that I hit shift-enter on my keyboard. No need to copy and paste things back and forth.

So what exactly is going on?

The code above is being run with JavaScript, but it’s not the only way that I can execute code and see the results in the document. There are many different languages that are supported. These are set up via “kernels.” When you install nteract, it comes with a special Node.js kernel installed. This allows running snippets of JavaScript code, like the one above.

How do I get it?

Head over to nteract.io and download the latest version for your operating system.

Food for Thought

As an experiment, I decided to try writing this entire post using nteract on my Mac. So far, so good. Let’s see if I feel the same way after I’ve written the second part of this post, where I will cover, among other points, how to install additional kernels for use with nteract.