# `DocShell.Generate.Livebooks`
[🔗](https://github.com/futhr/doc_shell/blob/v2.0.0/lib/doc_shell/generate/livebooks.ex#L1)

Indexes Livebook notebooks so they appear in navigation and search.

Teams that keep runnable notebooks alongside their code — onboarding walk
throughs, data explorations, incident playbooks — usually find them invisible
to the documentation site. This extractor walks a base directory for
`.livemd` files and produces the same content entries as any other source:

    %{
      "id" => "onboarding",
      "title" => "Onboarding walkthrough",
      "kind" => "livebook",
      "ast" => [...],
      "meta" => %{"source_path" => "notebooks/onboarding.livemd"}
    }

Livebook's format is Markdown, so the notebook parses with the ordinary
`DocShell.Ast` pipeline. Code cells arrive as fenced code blocks and
Livebook's `<!-- livebook:{...} -->` annotations as HTML comment nodes, which
a renderer can style, strip, or use to offer a "run in Livebook" link.
DocShell does not evaluate notebooks or interpret their outputs; the entry
describes the document as written.

The id is the filename without its extension and the title is the first
Markdown H1, which is where Livebook puts the notebook name. Unlike guides,
notebooks carry no frontmatter — Livebook owns the top of the file.

Files are sorted by path so the artifact is stable across builds.

# `extract`

```elixir
@spec extract(Path.t()) :: {:ok, [map()]} | {:error, term()}
```

Extracts every `.livemd` file found recursively beneath `base`.

A missing directory yields an empty list. The first unreadable file
short-circuits the run and returns `{:error, {path, reason}}`.

# `extract_file`

```elixir
@spec extract_file(Path.t()) :: {:ok, map()} | {:error, term()}
```

Extracts one `.livemd` file into a content entry.

---

*Consult [api-reference.md](api-reference.md) for complete listing*