Working with Code

In the Editor Basics, we saw how to add and work with all types of blocks inside a Nextjournal notebook. In this guide, we will have a closer look into a somewhat special block, the code cell, that allows you to execute code in different programming languages within your notebook. You can go directly for a quick visual summary of the code cell components, or keep reading for all the details.

Code Cells

All programming in Nextjournal starts by adding a code cell for the programming language that you want to work with. Nextjournal currently supports running the following programming languages: Python, R, Julia, Clojure, Bash, and Agda.

Adding a code cell

You can add a code cell by 1. clicking the “+” button below a block and selecting “Code Cell: [Language]”. Alternatively, type ```[Language] at the beginning of a paragraph, and then press Space , like we do here to add a Python code cell:

Runtimes

When you add a code cell for a programming language for the first time, you’ll see that Nextjournal automatically inserts a matching runtime, the computational environment (and its filesystem) that your code needs in order to be run. Nextjournal takes care of setting up the runtimes and configuring them for you, but you can also do it yourself.

A different runtime is created each time you add a code cell for a different programming language. Multiple code cells of the same language share the same runtime, and consequently the same filesystem - unless you change it.

The runtimes are shown in the sidebar to your left.

Automatic shutdown

Runtimes will shut down automatically after 20 minutes of being idle, i.e., no code being run. As the runtime shuts down, the filesystem is also reset - meaning that no changes that you may have made persist. To see how you can work around this, go to the Persisting cell results section.

Configuration

Having independent and configurable runtimes is a powerful feature that has interesting implications. To understand why, we need to get a bit more technical - the runtimes' environments are essentially Docker images, that can be exported and re-used wherever you want: not only within Nextjournal, but on your (or anyone's) machine. For a more in-depth look into runtimes, their configuration, and how to leverage them, see our Runtimes and environments guide, or the one on reusing environments.

Running Code Cells

Run a single cell

To run a code cell, click on the “play” button in the upper right corner of the cell, or press Cmd/Ctrl+Enter. The first run might take a little longer, since it will need to boot up the language runtime first. Once the runtime is running, the following code cells that belong to that runtime should be executed fairly quick (depending on what you are trying to accomplish).

Run a cell and go to the next one

Pressing Shift+Enter will run your currently focused code cell, and will jump to the next cell that uses the same language. If no next cell exists, Nextjournal will add a new cell with that language instead.

Run all cells

To run all cells, simply click on the “Play” button on your header (or press Options+CmD+Enter):

A green checkmark next to the cell entry on the sidebar implies that the code cell has been successfully run.

Additional run options

To discover more run options, focus on your code cell, and use the Command Bar that lives at the bottom of your screen, e.g., by entering in the search field the word Run.

What happens if I close my notebook while a cell is running?

Your code cell will keep running even if you close your notebook. The runtime will shut down, though, after 20 minutes of being idle.

Locking Code Cells

You may want to run some code cells only once, e.g., cells that download some datasets or packages, which can be time-consuming. It is handy then to lock your cell, meaning that it will remain untouched if you wish to re-run the rest of your code.

To lock it, use the “···” button next to the cell to view the Options menu, and find the “Lock cell” option - or press Cmd/Ctrl Shift O , and find the Lock cell option in the Command Bar. Even quicker: enter Lock cell in the Command Bar's search field.

Cell Results

If the cell output is written to stdout, it will be displayed it in a scrolling section right below your code.

Also other types of output, if expected, will be displayed below the cell. Based on the output type, Nextjournal might display it as text, data structure, table, image, or graph.

To change the result display type (if your mime type allows it), click on the “···” button, and find the Change Result Viewer... option:

Persisting cell results

All filesystems associated to each runtime are transient. This means once the runtime shuts down or you reset it, all results that you have obtained using the code cells are lost and all cells will have to be re-run to re-generate their results.

If you want to persist and version your results, make sure you write the code cell output to a special Nextjournal directory called /results. That way, when you, e.g., restore a version of your notebook with the Notebook History feature, the previous version of a file written in /results will be restored along with everything else in the notebook.

Any file written to /results can be referenced by any code cell, no matter the language it uses, either by using the code selection toolbox, or by Ctrl/Cmd+E. More on that here.

Viewing /results

Furthermore, any result written to /results will display it below your code using a viewer that’s automatically selected based on the result file’s mime type:

echo "Hi!" >> /results/hi.txt

Please mind that you won’t be able to list the contents of /results. Its sole purpose is to write to it so that Nextjournal can version and display it.

For more details on how to work with data and the /results directory, see our related guide.

Code Completion & Docs

Press Tab (or find the Code Completion option using the Command Bar), and Nextjournal will try to autocomplete the code that your cursor is currently in:

Similarly, press Shift+Tab (or look for the Code Docs option), and Nextjournal will try to present you with documentation about the currently active piece of code:

⚠️ ⚠️ ⚠️ For both of these features to work, your code cell’s associated runtime has to be running. If it is idle, running one of its cells will boot it up again.

Naming Cells

To name a cell, click on the “···” button next to the cell and look for the “Assign name...” option, or look for the option in the Command Bar, like we do below with Shift Ctrl/Cmd O:

Code Cell Overview

Errors

If you produce an error while running your program, Nextjournal will try to match the error to an offending line. If you are stuck, don't hesitate to use the “Help” button! You can use it to give us permission to help you out with your notebook.

Working with Code and Data

We hope that you found this guide useful! We recommend you play around with what you learned here, and head over to see how you can work with code and data in Nextjournal.