Eclair Notebooks

@variable syntax

Cells can be named. Reference another cell's output with @variable_name. Execution is topological — cells re-run when dependencies change.

Data files in data/ are auto-registered as @slug variables (e.g., data/aapl.csv becomes @aapl). CSV/TSV files are auto-parsed via d3.

Important: @variable references are rewritten at runtime. They must NOT appear inside string literals or comments in cell code — the replacement engine skips strings/comments, so @refs there will be left as-is (which is correct but may confuse authors).

Notebook format

{
  "name": "Notebook Name",
  "order": 0,
  "autoRun": true,
  "cells": [
    {
      "id": "unique-cell-id",
      "type": "markdown|code|python",
      "content": "cell content here",
      "name": "optional_variable_name",
      "order": 0
    }
  ]
}

Content formats

• Notebooks: .notebook.json in notebooks/
• Pages: .page.html in notebooks/ — custom HTML dashboards
• Slides: .slides.html in notebooks/ — presentations
• Documents: .doc.md in notebooks/ — markdown docs
• Examples: .example.json in examples/ — standalone snippets

Workflow

1. Discover: List notebooks/ to see what exists
2. Read: Open target .notebook.json and identify cells to modify
3. Edit: Make minimal changes to existing cells
4. Validate: Export touched notebooks, confirm data keys exist in data/
5. Report: Summarize changes and what was validated

Commands

# Development
deno task dev                    # Start dev server (port 8030)
deno task build:html             # Rebuild frontend from partials

# Export
deno task export:html            # All notebooks → self-contained HTML
deno run -A cli/export.ts -i notebooks/example.notebook.json --all -o ./images/

# Testing
deno task test                   # Run tests
deno fmt                         # Format code

Guardrails

• Prefer editing existing notebooks and cells over creating new ones
• Do not remove existing content unless explicitly requested
• Do not swap data-backed charts for mock data
• Keep chart conventions consistent with existing notebooks
• Use fetch('/data/filename') in standalone HTML files; use @slug only inside the Eclair app