Elements of a Nextjournal Article

A Comprehensive List of All Available Content Types

Philippa Markovics

Paragraphs and Lists

The paragraph is the simplest Nextjournal node type. Internally, paragraphs use a rich-text editing component for text styles: italic, bold, monospaced text and links.

You can embed inline nodes in paragraphs: mathematical formulas, like inline_formula not implemented, references to a code cell’s result, like

Lists

Lists are restricted to a single level at the moment. Typing * followed by a space into an empty paragraph quickly transforms the paragraph into a list:

• A list item,

  • followed by another list item that’s indented.

    • Yes, even more indentation happening here.

  • Back to the previous level.

  • And one more.

There are also numbered lists. Quickly add them by typing 1. followed by a space.

1. A list item,

   1. followed by another list item that’s indented.

      1. Yes, even more indentation happening here.

   2. Back to the previous level.

   3. And one more.

And todo lists! Add them by typing *[] followed by a space.

• A list item,

  • followed by another list item that’s indented.

    • Yes, even more indentation happening here.

  • Back to the previous level.

  • And one more.

Headings

Nothing too fancy here. Just headings at various levels.

Collapsible Sections

Level 1 headings can also be made collapsible. Use a block options menu to make them collapsible. This is handy for appendices or hiding setup/boilerplate code. A collapsible heading encapsulates all content following it until the next level 1 heading.

Appendix Example

Here is some text that should be collapsed but can be expanded.

Blockquotes

“I need to discuss science vs. engineering. Put glibly:In science if you know what you are doing you should not be doing it.In engineering if you do not know what you are doing you should not be doing it.” 

— Richard W. Hamming

Files and Images

Files can be uploaded straight to an article. Here is an example of an uploaded CSV file with global temperature data:

Files

Images

If the uploaded file is an image, including SVGs, it will be rendered inline. If the image size exceeds the article’s default content width, layout controls allow expanding the image width beyond the article boundaries.

Images may be captioned.

Wide Images

Standard Width Image

Framed Images

Code Cells

Executable code cells form the core of the editor. Some cells execute remotely, on the Nextjournal cluster (Bash, Clojure, Python, R and Julia) while others execute in the browser (Javascript and ClojureScript).

Runtimes and Environments

When adding the first cell for a particular language, a runtime is created along with it and added to the code panel. New cells using the same language are appended to the previously existing runtime.

Runtimes provide an isolated computational resource for code cells to run in. For remote execution, code cells that share a runtime share process state and an ephemeral filesystem in the form of a Docker container. Browser-based runtimes execute in a web worker.

Remote runtimes are templated from an environment: a Docker image providing initial filesystem state, a language runtime, and preinstalled software packages.

By default, each new runtime is based on the Nextjournal Default environment.

Bash Cells and Runtimes

Bash cells exhibit special behavior. If another language runtime exists, bash cells will be appended to that runtime. This way, you can perform command line work underneath the language process, such as installing Python packages or downloading data.

Referencing Files

As noted above, files can be uploaded directly to an article. They can be referenced in a code cell or paragraph by typing Ctrl/Cmd+E and selecting the file you want to reference.

This example takes the global-temperature.csv file uploaded above, reads it, and returns the first character from the file.

(require '[clojure.java.io :as io])

(with-open [reader (io/reader 
global-temperature.csv)]

  (char (.read reader)))

Results

Code cells, by default, display the result of the last expression and standard output it generates.

Certain result types, like simple data structures, plots and images, are given special treatment or enhanced by the editor.

Currently, Nextjournal provides the following result viewers:

Data (the default)

If the last expression is a data structure, it's rendered as an expandable tree.

{:number 1

 :string "A string"

 :nested-map {:key-1 1 :key-2 2}

 :nested-vector [1 2 3 [4 5 6]]}

Image Results

Images generated by cells are displayed automatically, under certain conditions. Here is an example of a R cell that’s generating an image of a plot.

svg('/results/my-plot.png')

hist(rnorm(200, 1), breaks=100)

dev.off()

Table Results

If the results is a data frame or CSV file, it will render as table that shows the first 10 entries of the result. Here’s a R cell that renders the mtcars demo data:

mtcars

Console Output

Process standard output and standard error are streamed to the browser, between the source code and the final result. Cell output can be toggled. This Bash cell lists the installed PyPi Python packages.

pip freeze

Working With Results

Writing Results to the Filesystem

Files written to a runtime are only accessible from within that runtime.

The special /results path exists for making a result file referenceable, permanent and downloadable. The cell below writes a file to /results and Nextjournal automatically does the rest:

echo "some results" >> /results/results-file.txt

ls /results

Referencing Results

The file is now downloadable in the browser and can be referenced from other code cells, or even from another article. All results on the filesystem can be referenced using Cmd/Ctrl+E in a code cell:

cat 
results-file.txt

Content Addressed Storage

A note on storage. It may surprise you that results-file.txt no longer exists in /results:

ls /results

All results are content-addressed. If results-file.txt is updated with new results, Nextjournal does not write over the original file. The reference,

This process is invisible to the end-user while providing immense flexibility and complete reproducibility.

Code Listings

Code listings are not executable — they're for showing syntax-highlighted code in a larger variety of languages.

(->> (read)

     eval

     prn

     (while true))

Custom Languages

Code Listings also have a special option for custom languages. Selection "Custom" from the languages menu removes syntax highlighting from the code listing and allows for a custom language label.

AddExp = AddExp "+" MulExp  -- plus

         | AddExp "-" MulExp  -- minus

         | MulExp

Formula

Formula can appear as block, where take up the whole width of the article, or inline, where they appear in the flow of a paragraph. Formula are written in LaTeX and rendered in-browser using katex.

Block Formulas

Inline Formulas

Here is some text showing inlined LaTeX for an amplitudeinline_formula not implemented, a frequencyinline_formula not implemented, and a phase inline_formula not implemented.

Embedding Tweets and Videos

Insert an embed node and simply paste in a link to a tweet or YouTube or Vimeo video. If the link is recognizable, the media will show.

Tweets

YouTube Videos

Vimeo Videos