Packages
livebook
0.18.1
0.19.8
0.19.7
0.19.6
0.19.5
0.19.4
0.19.3
0.19.2
0.19.1
0.19.0
0.18.6
0.18.5
0.18.4
0.18.3
0.18.2
0.18.1
0.18.0
0.17.3
0.17.2
0.17.1
0.17.0
0.16.4
0.16.3
0.16.2
0.16.1
0.16.0
0.15.5
0.15.4
0.15.3
0.15.2
0.15.1
0.15.0
0.14.7
0.14.6
0.14.5
0.14.4
0.14.3
0.14.2
0.14.1
0.14.0
0.14.0-rc.1
0.14.0-rc.0
0.13.3
0.13.2
0.13.1
0.13.0
0.12.1
0.12.0
0.11.4
0.11.3
0.11.2
0.11.1
0.11.0
0.10.0
0.9.3
0.9.2
0.9.1
0.9.0
0.8.2
0.8.1
0.8.0
0.7.2
0.7.1
0.7.0
0.6.3
0.6.2
0.6.1
0.6.0
0.5.2
0.5.1
0.5.0
0.4.1
0.4.0
0.3.2
0.3.1
0.3.0
0.2.3
0.2.2
0.2.1
0.2.0
0.1.2
0.1.1
0.1.0
Automate code & data workflows with interactive notebooks
Current section
Files
Jump to
Current section
Files
lib/livebook/live_markdown.ex
defmodule Livebook.LiveMarkdown do
# File format used to store Livebook notebooks.
#
# The format is a subset of Markdown, which means that every Live
# Markdown is valid Markdown. Live Markdown uses HTML comments for
# storing certain metadata, so we assume a Markdown standard that
# supports comments. On the other hand, not every Markdown is a
# valid Live Markdown file, however it can be imported as such by
# applying tiny changes and assumptions.
#
# Currently the Live Markdown format imposes the following rules:
#
# 1. The file should have a leading *Heading 1* which contains
# the notebook name.
#
# 2. Every *Heading 2* starts a new section.
#
# 3. Every Elixir/Erlang code block represents a Code cell.
#
# 4. Adjacent regular Markdown blocks represents a Markdown cell.
#
# 5. Comments of the format `<!-- livebook:json -->` may appear
# anywhere in the file and hold Livebook specific data. The
# data should be treated as opaque, but is either of the
# following:
#
# * description of a notebook object that cannot be naturally
# encoded using Markdown, such as Smart cell. In such case
# the JSON contains the `livebook_object` field
#
# * notebook, section or cell metadata
#
# * `{"force_markdown":true}` - an annotation forcing the next
# Markdown block to be treated as part of Markdown cell
# (relevant for Elixir/Erlang code blocks, which otherwise
# are interpreted as Code cells)
#
# * `{"break_markdown":true}` - an annotation splitting the
# markdown content into separate Markdown cells
#
# * `{"output":true}` - an annotation marking a code snippet
# as cell output
#
# * notebook stamp data with `"stamp"` and `"offset"` fields,
# placed at the very end of the file. For more details see
# `t:Livebook.Hubs.Provider.notebook_stamp/0`
#
# 6. An optional code block may appear between the notebook name
# heading and the first section heading. This block is parsed
# as the setup Code cell.
#
# 7. Any comments before the leading heading are kept.
#
# ## Example
#
# Here's an example LiveMarkdown file:
#
# # My notebook
#
# ## Section 1
#
# Make sure to install:
#
# * Erlang
# * Elixir
# * PostgreSQL
#
# <!-- livebook:{"reevaluate_automatically":true} -->
#
# ```elixir
# Enum.to_list(1..10)
# ```
#
# This is it for this section.
#
# ## Section 2
#
# ```elixir
# # More Elixir code
# ```
#
@doc """
The file extension used by Live Markdown files.
"""
def extension(), do: ".livemd"
@doc """
Converts the given notebook into a Markdown document.
## Options
* `:include_outputs` - whether to render cell outputs.
Only textual outputs are included. Defaults to the
value of `:persist_outputs` notebook attribute
"""
@spec notebook_to_livemd(Notebook.t(), keyword()) :: {String.t(), list(String.t())}
defdelegate notebook_to_livemd(notebook, opts \\ []), to: Livebook.LiveMarkdown.Export
@doc """
Converts the given Markdown document into a notebook data structure.
Returns the notebook structure and a list of informative messages/warnings
related to the imported input.
"""
@spec notebook_from_livemd(String.t()) ::
{Notebook.t(), %{warnings: list(String.t()), stamp_verified?: boolean()}}
defdelegate notebook_from_livemd(markdown), to: Livebook.LiveMarkdown.Import
end