DocShell.Generate.Livebooks (DocShell v0.1.0)

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

Summary

Functions

extract(base)

Extracts every .livemd file found recursively beneath base.

extract_file(path)

Extracts one .livemd file into a content entry.

Functions

extract(base)

@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(path)

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

Extracts one .livemd file into a content entry.