Observable Framework

https://observablehq.observablehq.cloud/framework
Admin
Observable Framework is an open-source static site generator for data apps, dashboards, and reports,...
Tokens:54,856
Snippets:504
Trust Score:4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Create New Observable Framework App with npm

Source: https://observablehq.observablehq.cloud/framework/getting-started

This command initializes a new Observable Framework project using npm. It prompts the user for project details and sets up a new application from a template. Ensure Node.js 18 or later is installed.

```bash
npx @observablehq/framework@latest create
```

--------------------------------

### HTML Grid and Card Layout Example

Source: https://observablehq.observablehq.cloud/framework/getting-started

Demonstrates using Framework's 'grid' and 'card' CSS classes to create a responsive two-column layout with cards. The grid collapses to a single column on narrow screens.

```html
<div class="grid grid-cols-2">
  <div class="card grid-colspan-2">one–two</div>
  <div class="card">three</div>
  <div class="card">four</div>
</div>

```

--------------------------------

### Python Data Loader Example

Source: https://observablehq.observablehq.cloud/framework/getting-started

A Python script demonstrating how to fetch weather data from an API and output it as JSON, suitable for use as a data loader in Observable Framework.

```python
import json
import requests
import sys

longitude = -122.47
latitude = 37.80

station = requests.get(f"https://api.weather.gov/points/{latitude},{longitude}").json()
forecast = requests.get(station["properties"]["forecastHourly"]).json()

json.dump(forecast, sys.stdout)

```

--------------------------------

### HTTP Server for Local Preview

Source: https://observablehq.observablehq.cloud/framework/getting-started

Demonstrates how to preview a built Observable Framework application locally using the 'http-server' package.

```bash
npx http-server dist

```

--------------------------------

### Start Observable Framework Development Server with npm

Source: https://observablehq.observablehq.cloud/framework/getting-started

Starts the local development server for Observable Framework using npm. This command enables live reloading and instant updates in the browser as code changes. The default port is 3000.

```bash
npm run dev
```

--------------------------------

### Setup and Local Development with Yarn Classic

Source: https://observablehq.observablehq.cloud/framework/contributing

Clones the Observable Framework repository and installs dependencies using Yarn Classic. It then starts the local preview server, which automatically restarts on TypeScript file changes. Visit http://127.0.0.1:3000 to view the live preview.

```shell
git clone git@github.com:observablehq/framework.git
cd framework
yarn
yarn dev
```

--------------------------------

### NPM and Yarn Build Commands

Source: https://observablehq.observablehq.cloud/framework/getting-started

Provides the commands to build an Observable Framework application for deployment using npm or Yarn.

```bash
npm run build

```

```bash
yarn build

```

--------------------------------

### Navigate to Project Directory

Source: https://observablehq.observablehq.cloud/framework/getting-started

After creating a new Framework project, navigate into the project's root directory using the `cd` command. This is necessary to run development commands.

```bash
cd hello-framework
```

--------------------------------

### Start Observable Framework Development Server with Yarn

Source: https://observablehq.observablehq.cloud/framework/getting-started

Starts the local development server for Observable Framework using Yarn. This command enables live reloading and instant updates in the browser as code changes. The default port is 3000.

```bash
yarn dev
```

--------------------------------

### Allow Remote Connections to Development Server (sudo)

Source: https://observablehq.observablehq.cloud/framework/getting-started

Starts the Observable Framework development server using npm, allowing remote connections by binding to all interfaces (0.0.0.0) and using a privileged port (80). Requires administrator privileges.

```bash
sudo npm run dev -- --host 0.0.0.0 --port 80
```

--------------------------------

### NPM and Yarn Update Commands

Source: https://observablehq.observablehq.cloud/framework/getting-started

Shows how to update project dependencies, including Framework itself, using npm or Yarn.

```bash
npm update

```

```bash
yarn upgrade

```

--------------------------------

### Execute Data Loader Manually - Node.js

Source: https://observablehq.observablehq.cloud/framework/getting-started

Example of manually running a data loader script using Node.js in the terminal. This is useful for testing data loader logic independently. The script is expected to output JSON to standard output if successful.

```bash
node src/data/forecast.json.js

```

--------------------------------

### Specify Port for Development Server (npm)

Source: https://observablehq.observablehq.cloud/framework/getting-started

Starts the Observable Framework development server using npm and specifies a custom port number (e.g., 4321). This is useful if the default port 3000 is already in use.

```bash
npm run dev -- --port 4321
```

--------------------------------

### Display Live JavaScript in Markdown - Framework

Source: https://observablehq.observablehq.cloud/framework/getting-started

Demonstrates how to embed and execute JavaScript within Markdown files for live updates. Supports dynamic content rendering directly in the browser. Requires the Framework environment.

```markdown
# Weather report

```js
display(1 + 2);
```

```

--------------------------------

### HTML Responsive Chart with Resize Helper

Source: https://observablehq.observablehq.cloud/framework/getting-started

Shows how to embed a responsive chart within a grid layout using Framework's 'resize' helper. The helper re-renders the chart based on the container's width.

```html
<div class="grid grid-cols-1">
  <div class="card">${resize((width) => temperaturePlot(forecast, {width}))}</div>
</div>

```

--------------------------------

### YAML Front Matter for Dashboard Theme and TOC

Source: https://observablehq.observablehq.cloud/framework/getting-started

Illustrates setting the 'dashboard' theme and disabling the table of contents ('toc') using YAML front matter in an Observable Framework project.

```yaml
---
theme: dashboard
toc: false
---

```

--------------------------------

### Render a Component with display() in JavaScript

Source: https://observablehq.observablehq.cloud/framework/getting-started

Demonstrates how to render a custom JavaScript component (in this case, `temperaturePlot`) on the page using the `display` function. This allows integrating complex UI elements defined as functions.

```javascript
display(temperaturePlot(forecast));
```

--------------------------------

### Create New Observable Framework Project

Source: https://context7.com/context7/observablehq_observablehq_cloud_framework/llms.txt

Command-line instructions to initialize a new Observable Framework project, including interactive configuration and commands for starting the development server and building for production.

```bash
# Create a new project interactively
npx @observablehq/framework@latest create

# Follow the prompts to configure:
# - Project directory (default: ./hello-framework)
# - Project title
# - Include sample files (yes/no)
# - Install dependencies (npm/yarn/pnpm)
# - Initialize git repository

# Change into project directory
cd hello-framework

# Start the development server
npm run dev

# Build for production
npm run build

# Preview the built site locally
npx http-server dist
```

--------------------------------

### Serve Static Site with http-server

Source: https://observablehq.observablehq.cloud/framework/contributing

Serves the generated static site locally using the http-server package. This allows you to view the built documentation before deploying it. Ensure http-server is installed globally or locally.

```shell
http-server docs/.observablehq/dist
```

--------------------------------

### Create a Temperature Forecast Chart with Observable Plot

Source: https://observablehq.observablehq.cloud/framework/getting-started

Shows how to generate a line chart of hourly temperature forecasts using Observable Plot. It configures x and y axes, and plots lines based on forecast data, demonstrating dynamic updates when data changes.

```javascript
display(
  Plot.plot({
    title: "Hourly temperature forecast",
    x: {type: "utc", ticks: "day", label: null},
    y: {grid: true, inset: 10, label: "Degrees (F)"},
    marks: [
      Plot.lineY(forecast.properties.periods, {
        x: "startTime",
        y: "temperature",
        z: null, // varying color, not series
        stroke: "temperature",
        curve: "step-after"
      })
    ]
  })
);
```

--------------------------------

### Load JSON Data with FileAttachment in JavaScript

Source: https://observablehq.observablehq.cloud/framework/getting-started

Demonstrates how to load JSON data from a file using the `FileAttachment` function in JavaScript within the Framework. This method enables static analysis for build optimization and security.

```javascript
const forecast = FileAttachment("./data/forecast.json").json();
```

--------------------------------

### Process JSON Data - Node.js

Source: https://observablehq.observablehq.cloud/framework/getting-started

A Node.js script to fetch hourly weather forecast data from the NWS API. It makes asynchronous requests to retrieve station metadata and then the forecast data, outputting the result as JSON. Handles potential fetch errors. Requires Node.js environment and fetch API availability.

```javascript
const longitude = -122.47;
const latitude = 37.80;

async function json(url) {
  const response = await fetch(url);
  if (!response.ok) throw new Error(`fetch failed: ${response.status}`);
  return await response.json();
}

const station = await json(`https://api.weather.gov/points/${latitude},${longitude}`);
const forecast = await json(station.properties.forecastHourly);

process.stdout.write(JSON.stringify(forecast));

```

--------------------------------

### Define a Reusable Temperature Chart Component in JavaScript

Source: https://observablehq.observablehq.cloud/framework/getting-started

Details how to encapsulate chart logic into a reusable JavaScript function (a component). This function accepts data and optional configuration like width, returning a Plot.plot instance, promoting code modularity and testability.

```javascript
function temperaturePlot(data, {width} = {}) {
  return Plot.plot({
    title: "Hourly temperature forecast",
    width,
    x: {type: "utc", ticks: "day", label: null},
    y: {grid: true, inset: 10, label: "Degrees (F)"},
    marks: [
      Plot.lineY(data.properties.periods, {
        x: "startTime",
        y: "temperature",
        z: null, // varying color, not series
        stroke: "temperature",
        curve: "step-after"
      })
    ]
  });
}
```

--------------------------------

### TeX Integral Example with Custom Macro

Source: https://observablehq.observablehq.cloud/framework/lib/tex

Shows an example of typesetting an integral formula and defining a custom macro using TeX. This demonstrates the flexibility and extensibility of the TeX integration.

```tex
\def\f#1#2{#1f(#2)}
\f\relax{x} = \int_{-\infty}^\infty
    \f{\hat}\xi\,e^{2 \pi i \xi x}
    \,d\xi

```

--------------------------------

### Markdown-it Plugin Registration (JavaScript)

Source: https://observablehq.observablehq.cloud/framework/config

Shows how to register external markdown-it plugins, using markdown-it-footnote as an example. Requires installing the plugin via npm or yarn before registration.

```javascript
import MarkdownItFootnote from "markdown-it-footnote";

export default {
  markdownIt: (md) => md.use(MarkdownItFootnote)
};

```

--------------------------------

### Advanced TeX Example with Square Root

Source: https://observablehq.observablehq.cloud/framework/lib/tex

Provides an example of a more complex mathematical formula involving a square root, typeset using the `tex` functionality. This showcases the ability to handle intricate mathematical structures.

```tex
c = \pm\sqrt{a^2 + b^2}

```

--------------------------------

### Markdown Headings Example

Source: https://observablehq.observablehq.cloud/framework/markdown

Provides examples of how to create different levels of headings using Markdown syntax, from the first-level heading ('#') to the second-level heading ('##'). This is a fundamental Markdown feature for structuring content.

```markdown
# A first-level heading
## A second-level heading
```

--------------------------------

### Install Python Packages from requirements.txt

Source: https://observablehq.observablehq.cloud/framework/data-loaders

Installs all Python packages listed in the 'requirements.txt' file within the active virtual environment. This is crucial for managing project dependencies.

```bash
pip install -r requirements.txt

```

--------------------------------

### Render DOT Diagram with Graphviz Syntax Examples

Source: https://observablehq.observablehq.cloud/framework/lib/dot

Provides various examples of DOT language syntax for rendering different types of graphs, including circular graphs, directed graphs, and graphs with subgraphs and specific node/edge attributes.

```dot
graph { n0 -- n1 -- n2 -- n3 -- n0 }
```

```dot
digraph { x -> y -> z }
```

```dot
digraph G {
  subgraph cluster_0 {
    a0 -> a1 -> a2 -> a3
    label = "process #1"
    color = lightblue
  }
  subgraph cluster_1 {
    b0 -> b1 -> b2 -> b3
    label = "process #2"
    color = orange
  }
  start -> a0
  start -> b0
  a1 -> b3
  b2 -> a3
  a3 -> a0
  a3 -> end
  b3 -> end
  start [shape = diamond]
  end [shape = square]
}
```

--------------------------------

### Mermaid Sequence Diagram Example

Source: https://observablehq.observablehq.cloud/framework/lib/mermaid

A sample Mermaid diagram illustrating a sequence diagram. This example showcases participant interactions and message flows, rendering within the Observable environment.

```mermaid
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
```

--------------------------------

### Example Project Structure (Tree View)

Source: https://observablehq.observablehq.cloud/framework/project-structure

Illustrates the typical directory and file layout of an Observable Cloud Framework project. This structure helps organize source files, components, data loaders, and configuration.

```tree
. 
├─ src                    # source root
│  ├─ .observablehq
│  │  ├─ cache            # data loader cache
│  │  └─ deploy.json      # deployment metadata
│  ├─ components
│  │  └─ dotmap.js        # shared JavaScript module
│  ├─ data
│  │  └─ quakes.csv.ts    # data loader
│  ├─ index.md            # home page
│  └─ quakes.md           # page
├─ .gitignore
├─ README.md
├─ observablehq.config.js # app configuration
├─ package.json           # node package dependencies
└─ yarn.lock              # node package lockfile

```

--------------------------------

### Display Data with the built-in display() function

Source: https://observablehq.observablehq.cloud/framework/getting-started

Illustrates the usage of the built-in `display` function, similar to `console.log`, to render values or expressions directly in the output. It's implicitly called when a code block contains an expression.

```javascript
display(forecast);
```

```javascript
1 + 2
```

--------------------------------

### Generate Data Snapshots with Data Loaders

Source: https://context7.com/context7/observablehq_observablehq_cloud_framework/llms.txt

Examples of data loaders written in JavaScript, Python, and Bash for preprocessing data into static snapshots at build time. These loaders can be used with various programming languages.

```javascript
// src/data/forecast.json.js - JavaScript data loader
const longitude = -122.47;
const latitude = 37.80;

async function json(url) {
  const response = await fetch(url);
  if (!response.ok) throw new Error(`fetch failed: ${response.status}`);
  return await response.json();
}

const station = await json(`https://api.weather.gov/points/${latitude},${longitude}`);
const forecast = await json(station.properties.forecastHourly);

process.stdout.write(JSON.stringify(forecast));
```

```python
# src/data/forecast.json.py - Python data loader
import json
import requests
import sys

longitude = -122.47
latitude = 37.80

station = requests.get(f"https://api.weather.gov/points/{latitude},{longitude}").json()
forecast = requests.get(station["properties"]["forecastHourly"]).json()

json.dump(forecast, sys.stdout)
```

```bash
# src/data/quakes.json.sh - Shell script data loader
curl -f https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_day.geojson
```

--------------------------------

### Perl Data Loader Example

Source: https://observablehq.observablehq.cloud/framework/data-loaders

A simple Perl data loader that prints 'Hello World' to standard output. It uses a shebang line to specify the interpreter.

```perl
#!/usr/bin/env perl

print("Hello World\n");


```

--------------------------------

### Directory Structure Example - Source and Output

Source: https://observablehq.observablehq.cloud/framework/imports

Illustrates the typical directory structure before and after the build process in the ObservableHQ Cloud Framework. It shows how source files are organized and how imported modules are copied and hashed into the output 'dist' directory.

```plaintext
.
├─ src
│  ├─ chart.js
│  └─ index.md
└─ …

```

And `index.md` includes a JavaScript code block that says:
```
import {Chart} from "./chart.js";

```

The resulting output root is:
```
.
├─ dist
│  ├─ _import
│  │  └─ chart.c79c2048.js
│  ├─ _observablehq
│  │  └─ … # additional assets
│  └─ index.html
└─ …

```

--------------------------------

### Mermaid Class Diagram Example

Source: https://observablehq.observablehq.cloud/framework/lib/mermaid

An example of a Mermaid class diagram. This snippet demonstrates defining classes, relationships (inheritance, composition, aggregation), and members within the Observable environment.

```mermaid
classDiagram
Class01 <|-- AveryLongClass : Cool
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 --> C2 : Where am i?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 <--> C2: Cool label
```

--------------------------------

### Build Static Site with Yarn

Source: https://observablehq.observablehq.cloud/framework/contributing

Generates the static version of the documentation site using the 'docs:build' command. This process creates the 'docs/.observablehq/dist' folder, which can then be served locally using a web server like 'http-server'.

```shell
yarn docs:build
```

--------------------------------

### Displaying a Table Input (JavaScript)

Source: https://observablehq.observablehq.cloud/framework/inputs

Provides an example of how to use the `Inputs.table` function to display tabular data. The table itself acts as an input, allowing users to select rows via checkboxes.

```javascript
Inputs.table(olympians)
```

--------------------------------

### Search Result Interface and External Link Example (TypeScript)

Source: https://observablehq.observablehq.cloud/framework/config

Defines the SearchResult interface and provides an example of how to add external links to the search index. The search feature can be enabled or extended with custom results.

```typescript
interface SearchResult {
  path: string;
  title: string | null;
  text: string;
  keywords?: string;
}

```

```typescript
export default {
  search: {
    async *index() {
      yield {
        path: "https://example.com",
        title: "Example",
        text: "This is an example of an external link."
      };
    }
  }
};

```

--------------------------------

### Creating Components with JavaScript and HTML Literal in Observable

Source: https://observablehq.observablehq.cloud/framework/javascript

Illustrates creating reusable UI components using JavaScript and the `html` tagged template literal. This example defines a `greeting` function that renders personalized HTML.

```javascript
function greeting(name) {
  return html`Hello, <i>${name}</i>!`;
}
```

--------------------------------

### Convert Observable Notebook to Markdown using npx

Source: https://observablehq.observablehq.cloud/framework/convert

This command-line method uses npx to execute the '@observablehq/framework' convert command, allowing notebook conversion to Markdown without requiring a local project setup. It supports specifying multiple notebook URLs.

```bash
npx @observablehq/framework@latest convert <notebook-url>
```

--------------------------------

### GitHub Actions Workflow for Deploying Framework App

Source: https://observablehq.observablehq.cloud/framework/deploying

This GitHub Actions workflow automates the deployment of an Observable Framework application to GitHub Pages. It triggers on pushes to the main branch, daily schedules, and manual dispatches. It checks out code, sets up Node.js, installs dependencies, builds the app, configures GitHub Pages, uploads the build artifact, and deploys the pages.

```yaml
name: Deploy

on:
  # Run this workflow whenever a new commit is pushed to main.
  push: {branches: [main]}
  # Run this workflow once per day, at 10:15 UTC
  schedule: [{cron: "15 10 * * *"}]
  # Run this workflow when triggered manually in GitHub’s UI.
  workflow_dispatch: {}

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v4
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4

```

--------------------------------

### DuckDB Extension Configuration (JavaScript)

Source: https://observablehq.observablehq.cloud/framework/config

Demonstrates how to configure DuckDB extensions, including enabling core extensions like 'spatial' and 'h3' with default settings, and providing detailed configuration for source, installation, and loading.

```javascript
export default {
  duckdb: {
    extensions: ["spatial", "h3"]
  }
};

```

```javascript
export default {
  duckdb: {
    extensions: {
      spatial: {
        source: "https://extensions.duckdb.org/",
        install: true,
        load: true
      },
      h3: {
        source: "https://community-extensions.duckdb.org/",
        install: true,
        load: true
      }
    }
  }
};

```

--------------------------------

### Import FileAttachment from observablehq:stdlib

Source: https://observablehq.observablehq.cloud/framework/imports

Imports the `FileAttachment` class from the `observablehq:stdlib` module. This is an example of using Framework's built-in libraries via the `observablehq:` protocol.

```javascript
import {FileAttachment} from "observablehq:stdlib";
```

--------------------------------

### Visualize Data with SQL and Plot

Source: https://observablehq.observablehq.cloud/framework/sql

Shows how to query data using the `sql` tagged template literal and then visualize it using the Plot library. This example demonstrates binning stars by brightness and creating a histogram with `Plot.rectY`. It assumes the `sql` tag and `Plot` are available in the environment.

```javascript
Plot.plot({
  x: {round: true, label: "phot_g_mean_mag"},
  marks: [
    Plot.axisY({tickFormat: (d) => d / 1000, label: "count (thousands)"}),
    Plot.rectY(await sql`
      SELECT FLOOR(phot_g_mean_mag / 0.2) * 0.2 AS mag1
           , mag1 + 0.2 AS mag2
           , COUNT() AS count
        FROM gaia
       WHERE phot_g_mean_mag IS NOT NULL
       GROUP BY 1
    `, {x1: "mag1", x2: "mag2", y: "count", tip: true})
  ]
})
```

--------------------------------

### Basic App Configuration (JavaScript)

Source: https://observablehq.observablehq.cloud/framework/config

Example of a basic configuration file for an Observable Cloud Framework app. It sets the application's title and defines the navigation sidebar content. This file allows for dynamic configuration by referencing environment variables.

```javascript
export default {
  title: "My awesome app",
  pages: [
    {name: "Getting ever more awesome", path: "/getting-awesome"},
    {name: "Being totally awesome", path: "/being-awesome"},
    {name: "Staying as awesome as ever", path: "/staying-awesome"}
  ]
};

```

--------------------------------

### Observable HQ Configuration File Example

Source: https://observablehq.observablehq.cloud/framework/project-structure

Demonstrates the structure of the `observablehq.config.js` file, used for configuring the Observable Cloud Framework application. This file defines aspects like sidebar navigation and the application's title. It can be written in TypeScript or JavaScript.

```javascript
export default {
  title: "My Observable App",
  pages: [
    // Define pages and sections for sidebar navigation
    {
      name: "section1",
      pages: [
        { name: "home", path: "/" },
        { name: "about", path: "/about" },
      ]
    },
    // ... other sections and pages
  ]
};

```

--------------------------------

### Load Files and Data with FileAttachment

Source: https://context7.com/context7/observablehq_observablehq_cloud_framework/llms.txt

JavaScript examples demonstrating how to load various file types, including JSON, CSV, Parquet, and images, as well as access file metadata using the `FileAttachment` API.

```javascript
// Load JSON data
const volcano = FileAttachment("volcano.json").json();

// Load CSV with type inference
const quakes = FileAttachment("data/quakes.csv").csv({typed: true});

// Load from ZIP archive (extracts automatically)
const metadata = FileAttachment("quakes/metadata.json").json();
const features = FileAttachment("quakes/features.csv").csv({typed: true});

// Load Apache Parquet
const gaia = FileAttachment("lib/gaia-sample.parquet").parquet();

// Load image for manipulation
const horse = await FileAttachment("horse.jpg").image();

// Access file metadata
const file = FileAttachment("volcano.json");
console.log(file.name, file.size, file.mimeType, file.lastModified);
```

--------------------------------

### Configured Text Input with Label, Placeholder, and Value

Source: https://observablehq.observablehq.cloud/framework/inputs/text

Demonstrates a text input with a user-defined label, placeholder text, and an initial value. This enhances usability by providing context and a default entry. The 'label' can be a string or HTML, 'placeholder' guides the user, and 'value' sets the initial content.

```javascript
const name = view(
  Inputs.text({
    label: "Name",
    placeholder: "Enter your name",
    value: "Anonymous"
  })
);

name
```

--------------------------------

### Parameterized Data Loader with Node.js util

Source: https://observablehq.observablehq.cloud/framework/params

An example of a parameterized data loader (`.csv.js`) that uses `parseArgs` from Node.js `util` to handle command-line arguments. It queries a PostgreSQL database to generate CSV data for a specific product.

```javascript
import {parseArgs} from "node:util";
import {csvFormat} from "d3-dsv";
import postgres from "postgres";

const sql = postgres(); // Note: uses psql environment variables

const {
  values: {product}
} = parseArgs({
  options: {product: {type: "string"}}
});

const sales = await sql`
  SELECT
    DATE(sale_date) AS sale_day,
    SUM(quantity) AS total_quantity_sold,
    SUM(total_amount) AS total_sales_amount
  FROM
    sales
  WHERE
    product_id = ${product}
  GROUP BY
    DATE(sale_date)
  ORDER BY
    sale_day
`;

process.stdout.write(csvFormat(sales));

await sql.end();
```

--------------------------------

### GitHub Actions CI/CD Workflow for Deployment

Source: https://context7.com/context7/observablehq_observablehq_cloud_framework/llms.txt

This YAML file defines a GitHub Actions workflow for deploying an Observable Cloud Framework project. It includes steps for checking out code, setting up Node.js, caching data loader outputs, installing dependencies, building the project, configuring GitHub Pages, uploading artifacts, and deploying to GitHub Pages. The workflow is triggered on pushes to the 'main' branch and scheduled runs.

```yaml
name: Deploy

on:
  push: {branches: [main]}
  schedule: [{cron: "15 10 * * *"}]
  workflow_dispatch: {}

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      # Optional: Cache data loader outputs
      - id: date
        run: echo "date=$(TZ=America/Los_Angeles date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
      - id: cache-data
        uses: actions/cache@v4
        with:
          path: src/.observablehq/cache
          key: data-${{ hashFiles('src/data/*') }}-${{ steps.date.outputs.date }}

      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v4
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4

```

--------------------------------

### Load Text File with Specific Encoding

Source: https://observablehq.observablehq.cloud/framework/files

This example shows how to load a text file with a specified encoding, in this case, 'utf-16be'. This allows handling files with different character encodings.

```javascript
const pryvit = FileAttachment("pryvit.txt").text("utf-16be");

```

--------------------------------

### Text File Input

Source: https://observablehq.observablehq.cloud/framework/inputs/file

Provides an example of a file input configured to accept only text files, including a label and a required setting. The text content can be read directly.

```javascript
const textfile = view(Inputs.file({label: "Text file", accept: ".txt", required: true}));

// To read text content:
// textfile.text()
```

--------------------------------

### Generating Line Charts with Observable Plot in Observable

Source: https://observablehq.observablehq.cloud/framework/javascript

Demonstrates generating a line chart using the Observable Plot library within a JavaScript block. This example visualizes Apple's stock price data.

```javascript
Plot.lineY(aapl, {x: "Date", y: "Close"}).plot({y: {grid: true}})

```

--------------------------------

### SQL Query for Data Aggregation for Visualization

Source: https://observablehq.observablehq.cloud/framework/sql

Perform data aggregation using SQL, preparing data for visualization. This example groups stars by sky bins and counts them, outputting results suitable for plotting.

```sql
SELECT
  floor(ra / 2) * 2 + 1 AS ra,
  floor(dec / 2) * 2 + 1 AS dec,
  count() AS count
FROM
  gaia
GROUP BY
  1,
  2

```

--------------------------------

### HTML for Responsive Iframe

Source: https://observablehq.observablehq.cloud/framework/-example-responsive-iframe

This HTML snippet embeds an iframe with a specified source and scrolling disabled. It is designed to be part of a responsive design where the iframe's dimensions are controlled by JavaScript.

```html
<iframe id="iframe" scrolling="no" src="./embed"></iframe>
```

--------------------------------

### Create and Display a Leaflet Map in Observable

Source: https://observablehq.observablehq.cloud/framework/lib/leaflet

Provides a code example for creating and displaying an interactive map using Leaflet within an Observable environment. It initializes a map in a specified div, sets the initial view, adds OpenStreetMap tiles, and places a marker with a popup. Dependencies include the Leaflet library.

```javascript
const div = display(document.createElement("div"));
div.style = "height: 400px;";

const map = L.map(div)
  .setView([51.505, -0.09], 13);

L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", {
  attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>'
})
  .addTo(map);

L.marker([51.5, -0.09])
  .addTo(map)
  .bindPopup("A nice popup<br> indicating a point of interest.")
  .openPopup();

```

--------------------------------

### Load Multiple Files into an Array

Source: https://observablehq.observablehq.cloud/framework/files

This example illustrates how to load multiple image files by creating an array of FileAttachment instances. The files are not loaded until a content method (like .image()) is invoked on the array elements.

```javascript
const frames = [
  FileAttachment("frame1.png"),
  FileAttachment("frame2.png"),
  FileAttachment("frame3.png"),
  FileAttachment("frame4.png"),
  FileAttachment("frame5.png"),
  FileAttachment("frame6.png"),
  FileAttachment("frame7.png"),
  FileAttachment("frame8.png"),
  FileAttachment("frame9.png")
];

```

--------------------------------

### Render Vega-Lite Chart from JSON Specification

Source: https://observablehq.observablehq.cloud/framework/lib/vega-lite

Shows how to render a Vega-Lite chart using a JSON view specification. This approach is useful for defining complex visualizations declaratively. It includes an example of loading data from a CSV file using FileAttachment.

```javascript
vl.render({
  spec: {
    width: 640,
    height: 400,
    data: {url: await FileAttachment("gistemp.csv").url(), format: {type: "csv"}},
    mark: "point",
    encoding: {
      x: {type: "temporal", field: "Date"},
      y: {type: "quantitative", field: "Anomaly"},
      color: {type: "quantitative", field: "Anomaly", scale: {range: "diverging", reverse: true}}
    }
  }
})

```

--------------------------------

### JavaScript Module Import Example

Source: https://observablehq.observablehq.cloud/framework/imports

This snippet demonstrates how a JavaScript module is imported within an Markdown file in the ObservableHQ Cloud Framework. The framework automatically rewrites the import path during the build process to point to a hashed file in the output directory, ensuring cache-breaking.

```javascript
import {Chart} from "./chart.js";

```

--------------------------------

### Create Interactive Force-Directed Graph with D3.js

Source: https://observablehq.observablehq.cloud/framework/lib/d3

An example demonstrating the creation of an interactive force-directed graph using D3.js. It includes setting up the simulation, defining links and nodes, rendering SVG elements, and handling the tick event for animation. The data is assumed to be available in a 'data' object.

```javascript
const width = 640;
const height = 640;
const color = d3.scaleOrdinal(d3.schemeObservable10);

// Copy the data to protect against mutation by d3.forceSimulation.
const links = data.links.map((d) => Object.create(d));
const nodes = data.nodes.map((d) => Object.create(d));

const simulation = d3.forceSimulation(nodes)
    .force("link", d3.forceLink(links).id((d) => d.id))
    .force("charge", d3.forceManyBody())
    .force("center", d3.forceCenter(width / 2, height / 2))
    .on("tick", ticked);

const svg = d3.create("svg")
    .attr("width", width)
    .attr("height", height)
    .attr("viewBox", [0, 0, width, height])
    .attr("style", "max-width: 100%; height: auto;");

const link = svg.append("g")
    .attr("stroke", "var(--theme-foreground-faint)")
    .attr("stroke-opacity", 0.6)
  .selectAll("line")
  .data(links)
  .join("line")
    .attr("stroke-width", (d) => Math.sqrt(d.value));

const node = svg.append("g")
    .attr("stroke", "var(--theme-background)")
    .attr("stroke-width", 1.5)
  .selectAll("circle")
  .data(nodes)
  .join("circle")
    .attr("r", 5)
    .attr("fill", (d) => color(d.group))
    .call(drag(simulation));

node.append("title")
    .text((d) => d.id);

function ticked() {
  link
      .attr("x1", (d) => d.source.x)
      .attr("y1", (d) => d.source.y)
      .attr("x2", (d) => d.target.x)
      .attr("y2", (d) => d.target.y);

  node
      .attr("cx", (d) => d.x)
      .attr("cy", (d) => d.y);
}

display(svg.node());

```

--------------------------------

### Configure Date Input with Label and Initial Value

Source: https://observablehq.observablehq.cloud/framework/inputs/date

This example shows how to create a date input with a specified label and an initial value. The initial value can be a Date object, a 'YYYY-MM-DD' string, or milliseconds since epoch. Providing a label enhances usability.

```javascript
const start = view(Inputs.date({label: "Start", value: "2021-09-21"}));
```

--------------------------------

### Import Default Export from npm Package

Source: https://observablehq.observablehq.cloud/framework/imports

This snippet demonstrates how to import the default export of a package from the npm registry using the `npm:` protocol. It's a common way to bring in libraries like 'canvas-confetti'. No external installation is required as the framework handles downloading and self-hosting.

```javascript
import confetti from "npm:canvas-confetti";
```

```javascript
import {default as confetti} from "npm:canvas-confetti";
```

--------------------------------

### Dynamic Theming Based on Dark Mode Preference

Source: https://observablehq.observablehq.cloud/framework/lib/generators

Provides an example of using the `dark` generator to dynamically set a color scheme for a Plot chart and adjust `mix-blend-mode`. This demonstrates how to adapt visual elements based on user's color scheme preference.

```javascript
Plot.plot({
  height: 260,
  color: {scheme: dark ? "turbo" : "ylgnbu"},
  marks: [
    Plot.rectY(
      olympians,
      Plot.binX(
        {y2: "count"},
        {
          x: "weight",
          fill: "weight",
          z: "sex",
          mixBlendMode: dark ? "screen" : "multiply"
        }
      )
    ),
    Plot.ruleY([0])
  ]
})
```

--------------------------------

### Create a radio input from a Map with custom format

Source: https://observablehq.observablehq.cloud/framework/inputs/radio

This snippet shows a radio input created from a Map, similar to the previous example, but with a custom `format` function. The format displays both the name (key) and the size in ounces (value) for each option.

```javascript
const size2 = view(
  Inputs.radio(
    new Map([
      ["Short", 8],
      ["Tall", 12],
      ["Grande", 16],
      ["Venti", 20]
    ]),
    {value: 12, label: "Size", format: ([name, value]) => `${name} (${value} oz)`}
  )
);
```

--------------------------------

### Import deck.gl Standalone Bundle

Source: https://observablehq.observablehq.cloud/framework/lib/deckgl

Demonstrates how to import the deck.gl standalone bundle using npm. This allows access to various components for building GPU-powered visualizations.

```javascript
import deck from "npm:deck.gl";
```

--------------------------------

### YAML Front Matter for UI Element Control

Source: https://observablehq.observablehq.cloud/framework/-example-responsive-iframe

This YAML front matter is used in Markdown files within Observable Framework to disable specific UI elements such as the sidebar, header, footer, and pager for the embedded content. These settings can also be applied globally in `observablehq.config.js`.

```yaml
---
sidebar: false
header: false
footer: false
pager: false
---
```

--------------------------------

### Import Named Exports and Namespaces from npm

Source: https://observablehq.observablehq.cloud/framework/imports

This code illustrates importing specific named exports or the entire module as a namespace from npm packages. This allows for more granular control over which parts of a library are used, potentially reducing bundle size. Examples include importing 'rollup' from 'd3-array' or the entire 'd3' library.

```javascript
import {rollup} from "npm:d3-array"; // a single named import
```

```javascript
import * as d3 from "npm:d3"; // import everything as a namespace
```

--------------------------------

### Project Configuration (JavaScript)

Source: https://context7.com/context7/observablehq_observablehq_cloud_framework/llms.txt

Defines project behavior and settings through an `observablehq.config.js` file. Allows customization of the project title, page structure for navigation, theme, custom stylesheets, DuckDB extensions, SQL table registration, search functionality, custom interpreters, and header/footer content.

```javascript
// observablehq.config.js
export default {
  title: "My Data Dashboard",

  // Define sidebar structure
  pages: [
    {
      name: "Analysis",
      open: true,
      pages: [
        {name: "Overview", path: "/analysis/overview"},
        {name: "Details", path: "/analysis/details"}
      ]
    }
  ],

  // Customize theme
  theme: ["air", "near-midnight", "alt", "wide"],

  // Custom stylesheet
  style: "custom-style.css",

  // Configure DuckDB extensions
  duckdb: {
    extensions: ["spatial", "h3"]
  },

  // Register SQL tables
  sql: {
    gaia: "./lib/gaia-sample.parquet",
    quakes: "./data/earthquakes.csv"
  },

  // Enable search
  search: true,

  // Add custom interpreters for data loaders
  interpreters: {
    ".pl": ["perl"],
    ".scpt": ["osascript"]
  },

  // Custom header/footer
  header: ({title, path}) => `<div class="header">${title}</div>`,
  footer: ({path}) => `<a href="https://github.com/example/repo/blob/main/src${path}.md">view source</a>`
};
```

--------------------------------

### Initialize and Manage deck.gl Instance

Source: https://observablehq.observablehq.cloud/framework/lib/deckgl

Initializes a `DeckGL` instance, targeting a specified container and configuring initial view state, tooltips, effects, and controllers. It includes cleanup logic to finalize the instance when the code re-runs.

```javascript
const deckInstance = new DeckGL({
  container,
  initialViewState,
  getTooltip,
  effects,
  controller: true
});

// clean up if this code re-runs
invalidation.then(() => {
  deckInstance.finalize();
  container.innerHTML = "";
});
```

--------------------------------

### Hypertext Literal - SVG Example with Plot Integration

Source: https://observablehq.observablehq.cloud/framework/lib/htl

Shows how to generate SVG elements using Hypertext Literal, integrating with a plotting library (Plot.js) to create charts. This example positions two bar charts side-by-side within an SVG container.

```javascript
svg`<svg width="400" height="120">
  <g>
    ${Plot.barY([3, 4, 2, 7, 5]).plot({margin: 20, width: 200, height: 120})}
  </g>
  <g transform="translate(200, 0)">
    ${Plot.barY([5, 1, 7, 6, 2]).plot({margin: 20, width: 200, height: 120})}
  </g>
</svg>`
```

--------------------------------

### Deploying to GitHub Pages (YAML)

Source: https://context7.com/context7/observablehq_observablehq_cloud_framework/llms.txt

Automates the build and deployment process for projects hosted on GitHub Pages using GitHub Actions. This configuration typically involves setting up workflows to build the project and deploy the output to the `gh-pages` branch.

```yaml

```

--------------------------------

### Importing Observable Inputs Library (JavaScript)

Source: https://observablehq.observablehq.cloud/framework/inputs

Demonstrates how to import the entire Observable Inputs library or specific input components. This is the first step to using any of the provided UI elements.

```javascript
import * as Inputs from "npm:@observablehq/inputs";
```

```javascript
import {button, color} from "npm:@observablehq/inputs";
```

--------------------------------

### Create a Disabled Date Input

Source: https://observablehq.observablehq.cloud/framework/inputs/date

This code example demonstrates how to disable a date input, preventing the user from changing its value. The `disabled` option renders the input as non-interactive.

```javascript
const fixed = view(Inputs.date({label: "Fixed date", value: "2021-01-01", disabled: true}));
```

--------------------------------

### Import Specific Entry Point from npm Package

Source: https://observablehq.observablehq.cloud/framework/imports

This code demonstrates importing a specific file or entry point within an npm package, rather than relying on the package's default export. This is useful for accessing specialized modules or optimizing bundle size by only including necessary components, such as the 'lite' entry point of the 'mime' package.

```javascript
import mime from "npm:mime/lite";
```

```javascript
import confetti from "npm:canvas-confetti/dist/confetti.module.mjs";
```

--------------------------------

### Cancel Animation with Invalidation Promise

Source: https://observablehq.observablehq.cloud/framework/reactivity

Demonstrates using the `invalidation` promise to cancel an ongoing animation loop when a new animation starts. This is useful for cleaning up resources like animation frames.

```javascript
const context1 = canvas1.getContext("2d");
const color = colors[clicks % 4]; // cycle through colors on click
const start = performance.now(); // when the animation started

let frame = requestAnimationFrame(function tick(now) {
  const t = Math.min(1, (now - start) / duration);
  context1.fillStyle = color;
  context1.fillRect(0, 0, t * canvas1.width, canvas1.height);
  if (t < 1) frame = requestAnimationFrame(tick);
});

invalidation.then(() => cancelAnimationFrame(frame));

```

--------------------------------

### Activate Python Virtual Environment (Windows)

Source: https://observablehq.observablehq.cloud/framework/data-loaders

Activates the Python virtual environment located in '.venv\Scripts\activate' on Windows systems. This ensures that Python packages installed within the venv are used.

```bash
.venv\Scripts\activate

```

--------------------------------

### Get Current Time with now

Source: https://observablehq.observablehq.cloud/framework/javascript

The 'now' reactive variable provides the current time in milliseconds since the Unix epoch. Code referencing 'now' runs continuously, suitable for simple animations.

```javascript
now
```

--------------------------------

### Theme Configuration Options (JavaScript)

Source: https://observablehq.observablehq.cloud/framework/config

Demonstrates various ways to configure the theme for an Observable Cloud Framework app. This includes setting a single theme, composing multiple themes, and applying themes via front matter for individual pages.

```javascript
theme: "light"

```

```javascript
theme: "dark"

```

```javascript
theme: "dashboard"

```

```javascript
theme: ["air", "near-midnight", "alt", "wide"]

```

--------------------------------

### Get Absolute URL of a File Attachment

Source: https://observablehq.observablehq.cloud/framework/files

This code shows how to retrieve the absolute URL of a file attachment using the .href property. This is useful for referencing files directly in HTML or other contexts.

```javascript
FileAttachment("volcano.json").href

```
Tokens:
Raw