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 , references to a code cell’s result, like , andnumbers that can be referenced in code cells, like temperature = ºC.
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 items
followed by another list item
Sections give structure to an article in a tree-like format. Sections can be nested. The section's nesting level defines its heading size and numbering.
2.1. Nesting Sections
A section’s nesting level can be changed by promoting or demoting the section via its action menu. Hover over a section to expose the ••• menu button in the gutter. Opening the action menu will show a Promote Heading or Demote Heading action depending on the section’s current nesting level.
2.1.1. Disabling Section Numbering
To disable the numerals appearing before section headings, open Article Settings and deactivate "Numbered Section Headings".
3. Files and Images
Files can be uploaded straight to an article. Here is an example of an uploaded CSV file with global temperature data:
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.
3.2.1. Wide Images
3.2.2. Standard Width Image
3.2.3. Framed Images
4. Code Cells
4.1. 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.
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.
4.2. 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.
Process standard output and standard error arestreamed 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.
Bash in Python
4.4. Working With Results
4.4.1. 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
Bash in Python
4.4.2. 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 the @ menu in a code cell, followed by Insert Reference:
snowy-kingBash in Python
4.4.3. Content Addressed Storage
A note on storage. It may surprise you that results-file.txt no longer exists in /results:
Bash in Python
All results are content-addressed. If results-file.txt is updated with new results, Nextjournal does not write over the original file. The reference, , will simply point to the new results. This provides a form of version control for everything written to the filesystem.
This process is invisible to the end-user while providing immense flexibility and complete reproducibility.
5. Code Listings
Code listings are not executable — they're for showing syntax-highlighted code in a larger variety of languages.
5.1. 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
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.
6.1. Block Formulas
6.2. Inline Formulas
Here is some text showing inlined LaTeX for an amplitude, a frequency, and a phase.
7. 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.