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 sort of 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.
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 clicking the “+” button below a block and selecting “Code Cell: [Language]”. Alternatively, simply type
```[Language] at the beginning of a paragraph, and then press
Space , like we do here to add a Python code cell:
When you add a code cell for a programming language for the first time, you’ll see that Nextjournal automatically inserts a matching runtime, which will be visible on the sidebar to your left. Runtimes are the computational environments (and their filesystems) that your code needs in order to be run. Nextjournal takes care of setting them up and configuring them for you, but you can also configure them further 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 (together with the list of code cells belonging to each runtime) are shown in the sidebar. What's more, you can click on the code cell entries to navigate to the corresponding cell, or inspect their status (inactive, running, done, or errored) displayed next to each list entry.
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.
Having independent and configurable runtimes is a powerful feature. 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. That way, the hassle of installing and managing dependencies all the time is eliminated, allowing you focus on your work, and making your work easily reproducible. For a more in-depth look into runtimes, their configuration, and how to leverage them, see our Runtimes and environments guide.
Running Code Cells
Run a single cell
To run a code cell, click the “play” button in the lower right corner the cell, or press
Cmd/Ctrl+Enter. The first run might take a little longer because 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
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 “Fast forward” button on your header (or press
A green checkmark next to the cell entry on the sidebar implies that the code cell has been successfully run.
Additional run options
To find more run options, click on the dropdown next to the “Fast forward” button in your header:
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 do so, use the “···” button next to the cell to view the “Options” menu, and find the “Lock cell” option.
If a code cell writes output to
stdout, e.g. when installing packages or listing a directory, it will display it in a scrolling section right below your code.
Further, if there is another type of output expected (e.g., a graph), it will be displayed below the cell, too. Based on the output type, Nextjournal might display it as text, data structure, table, image, or graph. You can also change the pre-selected viewer (given that your mime type has more than one corresponding view 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.
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:
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
Whenever you select some code in a code cell, you will see that a selection toolbox pops up that presents you with a Complete and Docs option.
Click Complete (or press
Tab), and Nextjournal will try to autocomplete the currently selected piece of code:
Similarly, if you click Docs (or press
Shift+Tab), Nextjournal will try to present you with documentation about the currently selected piece of code:
Please mind that 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.
Things may get a little hectic if you have a lot of code cells. It may be convenient to add a name to each cell, making it easier for you to navigate them through the code cell list in your sidebar. To do so, you can either click on the “···” button next to the cell and look for the “Assign name...” option, or you can click on the language name on the bottom right corner of the cell, like we do below:
Code Cell Overview
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.