livebook

# 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. 👇

```elixir
# 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:

```elixir
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 (<i class="ri-livebook-sections"></i>) 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!

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

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

<!-- livebook:{"branch_parent_index":2} -->

## 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:

```elixir
{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".

```elixir
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 (<i class="ri-livebook-save"></i>)
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](https://katex.org/docs/supported.html).

## 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
(<i class="ri-livebook-shortcuts"></i>) in the sidebar or
by pressing <kbd>?</kbd>.

## 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](/explore/notebooks/distributed-portals-with-elixir)
  notebook;

* Learn how Elixir integrates with Livebook in the
  [Elixir and Livebook](/explore/notebooks/elixir-and-livebook) notebook;

* Finally, remember Livebook is an open source project, so feel free to
  look into [the repository](https://github.com/livebook-dev/livebook)
  to contribute, report bugs, suggest features or just skim over the
  codebase.

Now go ahead and build something cool! 🚢