Welcome to Livebook

Introduction

We are happy you decided to give Livebook a try, hopefully it empowers you to build great stuff! 🚀

Livebook is a tool for crafting interactive and collaborative code notebooks. It is primarily meant as a tool for rapid prototyping - think of it as an IEx session combined with your editor. You can also use it for authoring shareable articles that people can easily run and play around with. Package authors can write notebooks as interactive tutorials and include them in their repository, so that users can easily download and run them locally.

Basic usage

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 Elixir cells to run your code!

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

# This is an Elixir 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 Elixir cell in the section below and see it evaluates immediately.

Notebook files

By default notebooks are kept in memory, which is fine for interactive hacking, but oftentimes you will want to save your work for later. Fortunately, notebooks can be persisted 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 essentially 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, reuse for blog posts, and even edit in a text editor.

Math

Livebook uses $\TeX$ syntax for math. 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} $$

You can explore all supported expressions here.

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 ?.

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! 🚢