Welcome to Livebook

Basic usage

Livebook is a tool for crafting interactive and collaborative code notebooks.

Each notebook consists of a number of cells, which serve as primary building blocks. There are Markdown cells (such as this one) that allow you to describe your work and Code cells to run your Elixir code!

To insert a new cell move your cursor between cells and click one of the revealed buttons. 👇

# This is a Code cell - as the name suggests that's where the code goes.
# To evaluate this cell, you can either press the "Evaluate" button above
# or use `Ctrl + Enter` (or Cmd + Enter on a Mac)!

message = "hey, grab yourself a cup of 🍵"

Subsequent cells have access to the bindings you’ve defined:

String.replace(message, "🍵", "☕")

Note however that bindings are not global, so each cell sees only stuff that goes above itself. This approach helps to keep the notebook clean and predictable as you keep working on it!

Sections

You can leverage so called sections to nicely group related cells together. Click on the “Book” icon () in the sidebar to reveal a list of all sections. As you can see, this approach helps to easily jump around the notebook, especially once it grows.

Let’s make use of this section to see how output is captured!

cats = ~w(😼 😹 😻 😺 😸 😽)

for _ <- 1..3 do
  cats
  |> Enum.take_random(3)
  |> Enum.join(" ")
  |> IO.puts()
end

Branching sections

Additionally, you can make a section branch out from any previous regular section. Hover over the section name to reveal available actions and click on the branch icon to select the parent section.

You still have access to all the previous data:

{message, cats}

The important characteristic of a branching section is that it runs independently from other sections and as such is well suited for running long computations “in background”.

Process.sleep(300_000)

Having this cell running, feel free to insert another Code cell in the section below and see it evaluates immediately.

Saving notebooks

By default, notebooks are stored in a temporary directory, which is fine for interactive hacking, but oftentimes you will want to save your work for later. Such can be done by clicking on the “Disk” icon () in the bottom-right corner and selecting the file location.

Notebooks are stored in live markdown format, which is the Markdown you know, with just a few assumptions on how particular elements are represented. Thanks to this approach you can easily keep notebooks under version control and get readable diffs. You can also easily preview those files and even edit them in a text editor.

Stepping up your workflow

Once you start using notebooks more, it’s gonna be beneficial to optimise how you move around. Livebook leverages the concept of navigation/insert modes and offers many shortcuts for common operations. Make sure to check out the shortcuts by clicking the “Keyboard” icon () in the sidebar or by pressing ?.

Markdown extensions

Livebook also include supports for links, mathematical expressions, and Mermaid diagrams.

Links

It is possible to link between Livebooks using Markdown’s link syntax. For example, [next chapter](chapter_2.livemd) could be used to link to a Livebook named chapter_2.livemd in the same directory as the current notebook. Once clicked, Livebook will automatically open up a new session to execute the linked notebook.

Math expressions

Livebook uses $\TeX$ syntax for math inside your Markdown cells. It supports both inline math, like $e^{\pi i} + 1 = 0$, as well as display math:

$$ S(x) = \frac{1}{1 + e^{-x}} = \frac{e^{x}}{e^{x} + 1} $$

To write your own, put your math expressions between \$ signs for inline math or \$\$ if you want display math. You can double click the formulas above to see how they are written.

You can explore all supported expressions in the KaTeX documentation.

Mermaid diagrams

Mermaid is a library for creating diagrams and visualizations using text and code. You can define those diagrams in your Markdown cells via ```mermaid blocks. Let’s see an example:

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

Next steps

That’s our quick intro to Livebook! Where to go next?

• If you are not familiar with Elixir, there is a fast paced introduction to the language in the Distributed portals with Elixir notebook;

• Learn how Elixir integrates with Livebook in the Elixir and Livebook notebook;

• Finally, remember Livebook is an open source project, so feel free to look into the repository to contribute, report bugs, suggest features or just skim over the codebase.

Now go ahead and build something cool! 🚢