Getting Started with Nextjournal

Nextjournal lets you mix interactive code, data, media, narrative and formula in a single hosted document - a Nextjournal article. Share articles with colleagues for editing, or publish them to the world so others can learn from or reuse your work.

We support server-side execution of Julia 0.6, Python 2 and 3 via Anaconda, and R 4.4.0. In the browser, we support ClojureScript and Javascript. No setup is required to get started, and installing packages is a breeze.

If you're familiar with environments like Jupyter, you'll feel at home here. However, there are important differences that we believe make Nextjournal articles ideal for conducting and publishing research.

This guide is an article - feel free to remix it and play around!

1.
Adding new content

We start out in Write Mode. Here we can add paragraphs, section headings, code cells, lists, and more. Hover and click between any section, and select a content type from the insert menu.

The Nextjournal insert menu

2.
Working with code cells

Each code cell runs in an insolated process on our servers. This differs from environments like Jupyter which rely on global scope. While Nextjournal supports scoping cells to other cells, we encourage this isolated approach. Learn more about scoping.

2.1.
Code cell basics

Use Shift-Enter to run a cell.

x = randn(500)
random
/
Julia

2.2.
Referencing values from other cells

Just start typing the name of the value — an autocompleter will pop up.

<video here>


2.3.
Bash cells for command line work

A special case code cell is a bash cell. These cells have access to the article's filesystem on the command line. This is useful for processing data, download files, installing packages, or just about anything.

which python; echo "I love my bash"
shrill-dust
/
Bash
/opt/conda/bin/python
I love my bash

2.4.
Bash cells for package installation

Nextjournal preinstalls useful packages. But you'll likely need to install others. Let's see how this is done in each supported language.

2.4.1.
Installing R packages

R packages are installed using the R interpreter. NOTE: Installing packages using a normal R code cell only works during a single session. Use a bash cell to persist any changes to the filesystem, like package installs.

R -e 'install.packages("readr")'
patient-bread
/
Bash

R version 3.4.1 (2017-06-30) -- "Single Candle"
Copyright (C) 2017 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> install.packages("readr")
Installing package into '/usr/local/lib/R/site-library'
(as 'lib' is unspecified)
trying URL 'https://cran.rstudio.com/src/contrib/readr_1.1.1.tar.gz'
Content type 'application/x-gzip' length 233793 bytes (228 KB)
==================================================
downloaded 228 KB

* installing *source* package 'readr' ...
** package 'readr' successfully unpacked and MD5 sums checked
** libs
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c Collector.cpp -o Collector.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c CollectorGuess.cpp -o CollectorGuess.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c Iconv.cpp -o Iconv.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c LocaleInfo.cpp -o LocaleInfo.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c RcppExports.cpp -o RcppExports.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c Reader.cpp -o Reader.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c Source.cpp -o Source.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c Tokenizer.cpp -o Tokenizer.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c TokenizerDelim.cpp -o TokenizerDelim.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c TokenizerFwf.cpp -o TokenizerFwf.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c TokenizerWs.cpp -o TokenizerWs.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c connection.cpp -o connection.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c datetime.cpp -o datetime.o
gcc -std=gnu99 -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c grisu3.c -o grisu3.o
gcc -std=gnu99 -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c init.c -o init.o
gcc -std=gnu99 -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c localtime.c -o localtime.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c parse.cpp -o parse.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c read.cpp -o read.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c type_convert.cpp -o type_convert.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c write.cpp -o write.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c write_connection.cpp -o write_connection.o
g++  -I/usr/share/R/include -DNDEBUG  -I"/usr/lib/R/site-library/Rcpp/include" -I"/usr/local/lib/R/site-library/BH/include"    -fpic  -g -O2 -fdebug-prefix-map=/build/r-base-X2xP8j/r-base-3.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2 -g  -c write_delim.cpp -o write_delim.o
g++ -shared -L/usr/lib/R/lib -Wl,-Bsymbolic-functions -Wl,-z,relro -o readr.so Collector.o CollectorGuess.o Iconv.o LocaleInfo.o RcppExports.o Reader.o Source.o Tokenizer.o TokenizerDelim.o TokenizerFwf.o TokenizerWs.o connection.o datetime.o grisu3.o init.o localtime.o parse.o read.o type_convert.o write.o write_connection.o write_delim.o -L/usr/lib/R/lib -lR
installing to /usr/local/lib/R/site-library/readr/libs
** R
** inst
** preparing package for lazy loading
** help
*** installing help indices
** building package indices
** installing vignettes
** testing if installed package can be loaded
* DONE (readr)

The downloaded source packages are in
	'/tmp/RtmpESy5xy/downloaded_packages'
> 
> 

2.4.2.
Installing Python packages with Anaconda

Nextjournal preinstalls the conda package manager.

conda install -y -c bioconda cufflinks
snowy-voice
/
Bash
Fetching package metadata ...........
Solving package specifications: .
cufflinks-2.2.   1% |            cufflinks-2.2.   3% |                            cufflinks-2.2.   4% |#                              | Time: 0:00:ccufflinks-2.2.   cufflinks-2.2.   9% |###         cufflinks-2.2.  11% |###                         cufflinks-2.2.  13% |####                           | Time: 0:00:ccufflinks-2.2.  1cufflinks-2.2.  18% |#####       cufflinks-2.2.  19% |######                      cufflinks-2.2.  21% |######                         | Time: 0:00:ccufflinks-2.2.  2cufflinks-2.2.  26% |########    cufflinks-2.2.  28% |########                    cufflinks-2.2.  29% |#########                      | Time: 0:00:ccufflinks-2.2.  3cufflinks-2.2.  34% |##########  cufflinks-2.2.  36% |###########                 cufflinks-2.2.  38% |###########                    | Time: 0:00:ccufflinks-2.2.  4cufflinks-2.2.  43% |############cufflinks-2.2.  44% |#############               cufflinks-2.2.  46% |##############                 | Time: 0:00:ccufflinks-2.2.  4cufflinks-2.2.  51% |############cufflinks-2.2.  53% |################            cufflinks-2.2.  54% |################               | Time: 0:00:ccufflinks-2.2.  5cufflinks-2.2.  59% |############cufflinks-2.2.  61% |###################         cufflinks-2.2.  63% |###################            | Time: 0:00:ccufflinks-2.2.  6cufflinks-2.2.  68% |############cufflinks-2.2.  69% |#####################       cufflinks-2.2.  71% |######################         | Time: 0:00:ccufflinks-2.2.  7cufflinks-2.2.  76% |############cufflinks-2.2.  78% |########################    cufflinks-2.2.  79% |########################       | Time: 0:00:ccufflinks-2.2.  8cufflinks-2.2.  84% |############cufflinks-2.2.  86% |##########################  cufflinks-2.2.  88% |###########################    | Time: 0:00:ccufflinks-2.2.  9cufflinks-2.2.  93% |############cufflinks-2.2.  94% |############################cufflinks-2.2.  96% |#############################  | Time: 0:00:ccufflinks-2.2.  9

Try running this cell with Shift-Enter. Note that we don't have to constantly re-run our installation cell. If it doesn't change, we can continue working in other cells without waiting for it to run again.

3.
Uploading Files

Upload a file via the insert menu.

<add screenshot or video>

You can reference an uploaded file from a code cell. Start typing the name of the file to autocomplete the full name with the tab key.

census_data_20170821_599af17e5d64c.csv
Open in new window
import pandas
print(pandas.read_csv(census_data_20170821_599af17e5d64c.csv))
wild-fog
/
Python
                                                                                                                                         Five Year Age Groups and Sex for Region Summary
Region        Country Year Age   Both Sexes Population Male Population Female Population Percent Both Sexes Percent Male Percent Female                                        Sex Ratio
Custom Region Nigeria 2014 Total 177155754             90350541        86805213          100.0              100.0        100.0                                                     104.1
                           0-4   29154053              14926293        14227760          16.5               16.5         16.4                                                      104.9
                           5-9   25138706              12862588        12276118          14.2               14.2         14.1                                                      104.8
                           10-14 22212282              11362423        10849859          12.5               12.6         12.5                                                      104.7
                           15-19 18411640              9413431         8998209           10.4               10.4         10.4                                                      104.6
                           20-24 15807010              8072686         7734324           8.9                8.9          8.9                                                       104.4
                           25-29 13624906              6959590         6665316           7.7                7.7          7.7                                                       104.4
                           30-34 11788623              6043909         5744714           6.7                6.7          6.6                                                       105.2
                           35-39 9753209               5030607         4722602           5.5                5.6          5.4                                                       106.5
                           40-44 7688913               4006142         3682771           4.3                4.4          4.2                                                       108.8
                           45-49 6175196               3173742         3001454           3.5                3.5          3.5                                                       105.7
                           50-54 4952613               2483654         2468959           2.8                2.7          2.8                                                       100.6
                           55-59 3881005               1905090         1975915           2.2                2.1          2.3                                                        96.4
                           60-64 3083927               1488541         1595386           1.7                1.6          1.8                                                        93.3
                           65-69 2381655               1150706         1230949           1.3                1.3          1.4                                                        93.5
                           70-74 1599245               770981          828264            0.9                0.9          1.0                                                        93.1
                           75-79 921052                436126          484926            0.5                0.5          0.6                                                        89.9
                           80-84 422138                194251          227887            0.2                0.2          0.3                                                        85.2
                           85-89 132037                58359           73678             0.1                0.1          0.1                                                        79.2
                           90-94 24870                 10382           14488             0.0                0.0          0.0                                                        71.7
                           95-99 2537                  989             1548              0.0                0.0          0.0                                                        63.9
                           100+  137                   51              86                0.0                0.0          0.0                                                        59.3

4.
Writing files for referencing in cells

Similar to uploaded files, files written to /results show up in the article and can be referenced.

fileConn<-file("/results/output.txt")
writeLines(c("Welcome","To","Nextjournal"), fileConn)
close(fileConn)
writing files
/
R
cat writing files.output.txt
bitter-rain
/
Bash
Welcome
To
Nextjournal

5.
Reordering content in Outline Mode

Instead of copying and pasting, use Outline Mode to move your article's content. Switching to Outline Mode, we see a compact overview of our article.

6.
Plotting Data

For displaying plots automatically after a cell, each language supports a handful of specific plotting libraries. Let's review them.

6.1.
Plotting in Julia

The Plots library is preinstalled. It provides a unified interface to different plotting libraries. We support Plotly (the default) and GR out of the box - Plotly is the default. Plotly graphs are interactive. GR is faster for large data sets such as those used to generate spectrograms in our article on waveforms.

Let's plot this cubic curve using both.

points = readcsv(cubic.csv)
Plots.plotly()
Plots.scatter(points)
cubic curve
/
Julia
points = readcsv(cubic.csv)
Plots.gr()
Plots.scatter(points)
delicate-sunset
/
Julia
INFO: Precompiling module GR.
GKS: can't open display on ""
     Is your DISPLAY environment variable set correctly?
     Did you enable X11 and TCP forwarding?

GKS: Open failed in routine OPEN_WS
GKS: GKS not in proper state. GKS must be either in the state WSOP or WSAC in routine ACTIVATE_WS

6.2.
Plotting in Python

Python cells support plotly and matplotlib out of the box.

import matplotlib
matplotlib.use('agg')
import pandas as pd
import plotly.plotly as py
import matplotlib.pyplot as plt

df = pd.read_csv(cubic.csv)
fig = plt.figure()
ax = fig.add_subplot(111)
ax.plot(df)
fig
polished-forest
/
Python

6.3.
Plotting in R

R cells support plotly and ggplot2 out of the box.

library(plotly)
df = read.csv(cubic.csv)
plot_ly(data = df, type = "scatter", mode = "markers")
raspy-glitter
/
R


7.
Writing math with KaTeX

Nextjournal uses the Khan Academy KaTeX library for writing math.

Write inline formula by typing @ in a paragraph: Asin(ωt+ϕ)A \sin\left(\omega t+\phi\right)

<video here>

Use the insert menu to add a larger formula on its own line.

A(t)=Asin(2πft+ϕ)=Asin(ωt+ϕ)A(t) = A \sin\left(2\pi f t + \phi\right) = A \sin\left(\omega t+\phi\right)

8.
Using Coders to display customized results

Do you need to display a custom result type, like an SVG image? Coders allow you to display a file with a custom mime type. Nextjournal support for inline display of Python's Matplotib or plotly graphs is written as coders.

Let's build a coder to display SVG generated by the Python svgwrite library and the register_coder function.

pip install svgwrite
install svgwrite
/
Bash
Collecting svgwrite
  Downloading svgwrite-1.1.11-py2.py3-none-any.whl (64kB)
Requirement already satisfied: pyparsing>=2.0.1 in /opt/conda/lib/python2.7/site-packages (from svgwrite)
Installing collected packages: svgwrite
Successfully installed svgwrite-1.1.11
import svgwrite
from svgwrite import cm, mm   

def write_svg(svg, path):
  with open(path, "w") as f:
    f.write(svg.tostring())
  return {'kind': 'file', 'content_type': 'image/svg+xml'}

register_coder("svg",
  lambda value: isinstance(value, svgwrite.Drawing),
  lambda value, path: write_svg(value, path))

dwg = svgwrite.Drawing("/tmp/base.svg", (300, 300))
r = dwg.circle(center=(150, 150), r='2.5cm', fill='white',stroke='blue')
dwg.add(r)
dwg
svg coder
/
Python

Coming soon: Here's how we do it in Julia.

And in R.