jeffgallini · jeffgallini · Sep 2, 2026 · Sep 2, 2026
diff --git a/docs/README.md b/docs/README.md
@@ -3,6 +3,19 @@
 This directory is published to **https://jeffgallini.github.io/dash-globe/** by
 [`.github/workflows/docs.yml`](../.github/workflows/docs.yml).
 
+## Pages
+
+| Path | Purpose |
+| --- | --- |
+| `index.html` / `index.md` | Home |
+| `getting-started.html` / `getting-started.md` | Quick start |
+| `api.html` / `api.md` | Python API reference |
+| `examples.html` / `examples.md` | Example gallery |
+| `llms.txt` | LLM-oriented site map ([llms.txt spec](https://llmstxt.org/)) |
+
+Markdown siblings and `llms.txt` are for agents; HTML pages include
+`rel="alternate"` / `rel="describedby"` links to them.
+
 ## Local preview
 
 Open `docs/index.html` in a browser, or:
@@ -11,6 +24,12 @@ Open `docs/index.html` in a browser, or:
 python -m http.server 8080 --directory docs
 ```
 
+Then visit:
+
+- http://127.0.0.1:8080/
+- http://127.0.0.1:8080/api.html
+- http://127.0.0.1:8080/llms.txt
+
 ## Refresh example media
 
 With the gallery running (`python dash_globe/usage.py`):

diff --git a/docs/api.html b/docs/api.html
diff --git a/docs/api.md b/docs/api.md
@@ -0,0 +1,117 @@
+# Dash Globe Python API
+
+> Chainable Python API for building interactive 3D globes in Dash on top of [react-globe.gl](https://github.com/vasturiano/react-globe.gl).
+
+Install: `pip install dash-globe`
+
+HTML version: [api.html](./api.html)
+
+## Imports
+
+```python
+import dash_globe
+
+globe = dash_globe.DashGlobe(id="globe")
+dash_globe.PRESETS
+dash_globe.data_url(...)
+dash_globe.event_coords(...)
+dash_globe.material_spec(...)
+dash_globe.lambert_material(...)
+dash_globe.ring_color_interpolator(...)
+```
+
+Public exports: `DashGlobe`, `PRESETS`, `data_url`, `is_data_url`, `event_coords`, `ring_color_interpolator`, `material_spec`, `lambert_material`.
+
+## DashGlobe
+
+`DashGlobe(*args, **kwargs)` subclasses the generated Dash component and defaults `responsive=True`. Every helper returns `self` for chaining.
+
+`update(**kwargs)` sets props in place. Snake-case aliases map to camelCase component props (`background_color` → `backgroundColor`).
+
+### Scene helpers
+
+- `update_layout(width=, height=, responsive=, background_color=, background_image_url=, globe_offset=, wait_for_globe_ready=, animate_in=, renderer_config=, style=, class_name=)`
+- `update_globe(globe_image_url=, bump_image_url=, show_globe=, show_graticules=, show_atmosphere=, atmosphere_color=, atmosphere_altitude=, curvature_resolution=)`
+- `update_view(lat=, lng=, altitude=, transition_duration=)`
+- `update_controls(auto_rotate=, auto_rotate_speed=)`
+- `update_interaction(enable_pointer_interaction=, show_pointer_cursor=, line_hover_precision=, animation_paused=, current_view_report_interval=)`
+- `update_day_night_cycle(enabled=, day_image_url=, night_image_url=, time=, animate=, minutes_per_second=)`
+- `update_clouds(enabled=, image_url=, altitude=, rotation_speed=, opacity=)`
+- `clear_tile_cache()`
+
+### Layers
+
+Each layer supports `add_*` (append) and `update_*` (replace data / set accessors):
+
+| Layer | Methods |
+| --- | --- |
+| Points | `add_points`, `update_points` |
+| Arcs | `add_arcs`, `update_arcs` |
+| Polygons | `add_polygons`, `update_polygons` |
+| Paths | `add_paths`, `update_paths` |
+| Heatmaps | `add_heatmap`, `add_heatmaps`, `update_heatmap`, `update_heatmaps` |
+| Hex bins | `add_hex_bins`, `update_hex_bins` |
+| Hex polygons | `add_hex_polygons`, `update_hex_polygons` |
+| Tiles | `add_tiles`, `update_tiles` |
+| Particles | `add_particle_sets`, `update_particles` |
+| Rings | `add_rings`, `update_rings` |
+| Labels | `add_labels`, `update_labels` |
+| HTML overlays | `add_html_elements`, `update_html_elements` |
+
+Accessors accept constants or string field paths (`"lat"`, `"properties.ADMIN"`).
+
+### Large data
+
+```python
+globe = (
+    dash_globe.DashGlobe(id="countries")
+    .enable_large_data_mode()
+    .update_polygons(
+        data=dash_globe.data_url(
+            "https://raw.githubusercontent.com/vasturiano/react-globe.gl/master/example/datasets/ne_110m_admin_0_countries.geojson"
+        ),
+        polygon_geo_json_geometry="geometry",
+        polygon_cap_color="rgba(56, 189, 248, 0.55)",
+        polygon_label="properties.ADMIN",
+    )
+)
+```
+
+`data_url(url, unwrap_features=True)` builds a client-fetch marker so large GeoJSON never enters the Dash layout. `enable_large_data_mode()` turns on summary event payloads and other large-data defaults.
+
+## Helpers
+
+### PRESETS
+
+Texture URLs: `EARTH`, `EARTH_DAY`, `EARTH_NIGHT`, `EARTH_DARK`, `EARTH_TOPOGRAPHY`, `EARTH_WATER`, `NIGHT_SKY`, `CLOUDS`.
+
+### event_coords(event)
+
+Returns `{"lat", "lng", "altitude?"}` from `clickData` / `hoverData`, or `None`.
+
+### material_spec / lambert_material
+
+JSON material specs for tiles. Types: `basic`, `lambert`, `phong`, `standard`. Side: `front`, `back`, `double`.
+
+### ring_color_interpolator
+
+Serialisable ring fade spec. Easing: `linear`, `sqrt`, `square`, `cubic`.
+
+## Events
+
+Dash callback props: `clickData`, `rightClickData`, `hoverData`, `currentView`. Payload size controlled by `eventDataMode` (`"summary"` | `"full"`).
+
+```python
+from dash import Input, Output, callback
+import dash_globe
+
+@callback(Output("out", "children"), Input("globe", "clickData"))
+def on_click(click_data):
+    return str(dash_globe.event_coords(click_data))
+```
+
+## Notes
+
+- Focus is JSON-serialisable `react-globe.gl` features that map cleanly to Dash.
+- Raw JS functions, DOM nodes, and arbitrary Three.js objects are not exposed through high-level helpers.
+- Source: [dash_globe/globe.py](https://github.com/jeffgallini/dash-globe/blob/master/dash_globe/dash_globe/globe.py)
diff --git a/docs/assets/site.css b/docs/assets/site.css
@@ -246,9 +246,127 @@ h3 { font-size: 1.15rem; margin-bottom: 0.45rem; }
   flex-wrap: wrap;
 }
 
+.api-layout {
+  display: grid;
+  grid-template-columns: 220px minmax(0, 1fr);
+  gap: 2rem;
+  align-items: start;
+}
+
+.api-toc {
+  position: sticky;
+  top: 88px;
+  padding: 1rem;
+  border: 1px solid var(--border);
+  border-radius: 14px;
+  background: rgba(19, 35, 56, 0.72);
+}
+
+.api-toc h2 {
+  font-size: 0.85rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--muted);
+  margin-bottom: 0.85rem;
+}
+
+.api-toc nav {
+  display: flex;
+  flex-direction: column;
+  gap: 0.55rem;
+}
+
+.api-toc a {
+  color: var(--muted);
+  font-size: 0.92rem;
+}
+
+.api-toc a:hover {
+  color: var(--text);
+}
+
+.api-section + .api-section {
+  margin-top: 2.5rem;
+  padding-top: 2rem;
+  border-top: 1px solid var(--border);
+}
+
+.method {
+  margin: 1.25rem 0;
+  padding: 1rem 1.1rem;
+  border: 1px solid var(--border);
+  border-radius: 14px;
+  background: rgba(7, 17, 29, 0.72);
+}
+
+.method h3 {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 1rem;
+  color: #d7e6f7;
+}
+
+.method p {
+  color: var(--muted);
+  line-height: 1.65;
+  margin: 0.65rem 0 0;
+}
+
+.method .sig {
+  margin-top: 0.75rem;
+  overflow-x: auto;
+  padding: 0.7rem 0.85rem;
+  border-radius: 10px;
+  border: 1px solid var(--border);
+  background: #050d16;
+  color: #9fd0ff;
+  font-size: 0.84rem;
+  line-height: 1.5;
+}
+
+.param-table {
+  width: 100%;
+  border-collapse: collapse;
+  margin-top: 0.9rem;
+  font-size: 0.9rem;
+}
+
+.param-table th,
+.param-table td {
+  text-align: left;
+  vertical-align: top;
+  padding: 0.55rem 0.45rem;
+  border-bottom: 1px solid var(--border);
+}
+
+.param-table th {
+  color: var(--muted);
+  font-weight: 650;
+}
+
+.param-table code {
+  color: #d7e6f7;
+}
+
+.note {
+  margin-top: 1rem;
+  padding: 0.9rem 1rem;
+  border-left: 3px solid var(--accent);
+  background: rgba(77, 163, 255, 0.08);
+  color: var(--muted);
+  line-height: 1.65;
+}
+
 @media (max-width: 900px) {
   .hero {
     grid-template-columns: 1fr;
     padding-top: 2.5rem;
   }
+
+  .api-layout {
+    grid-template-columns: 1fr;
+  }
+
+  .api-toc {
+    position: static;
+  }
 }
diff --git a/docs/examples.html b/docs/examples.html
@@ -5,18 +5,22 @@
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>Examples · Dash Globe</title>
   <link rel="stylesheet" href="assets/site.css" />
+  <link rel="alternate" type="text/markdown" href="examples.md" />
+  <link rel="describedby" href="llms.txt" />
 </head>
 <body>
   <header class="site-header">
     <div class="wrap">
       <a class="brand" href="index.html">
-        <span class="brand-mark" aria-hidden="true">🌐</span>
+        <span class="brand-mark" aria-hidden="true"></span>
         <span>Dash Globe</span>
       </a>
       <nav class="nav">
         <a href="index.html">Home</a>
         <a href="getting-started.html">Getting Started</a>
+        <a href="api.html">API</a>
         <a class="active" href="examples.html">Examples</a>
+        <a href="llms.txt">llms.txt</a>
         <a href="https://github.com/jeffgallini/dash-globe">GitHub</a>
         <a href="https://pypi.org/project/dash-globe/">PyPI</a>
       </nav>
@@ -100,7 +104,7 @@ <h2>Run the interactive gallery</h2>
   <footer class="footer">
     <div class="wrap">
       <div>Dash Globe v1.0.0</div>
-      <div><a href="getting-started.html">Getting started →</a></div>
+      <div><a href="api.html">API reference →</a></div>
     </div>
   </footer>
 </body>

diff --git a/docs/examples.md b/docs/examples.md
@@ -0,0 +1,27 @@
+# Examples · Dash Globe
+
+> Captured from the interactive `usage.py` gallery. Prefer GIFs where the scene animates; otherwise a still PNG shows the rendered state.
+
+HTML version: [examples.html](./examples.html)
+
+## Gallery
+
+- **Basic Points** — Night-earth texture with random colored altitude points (`assets/examples/basic-points.png`)
+- **Random Arcs** — Dashed arcs with per-arc dash timing authored in Python (`assets/examples/random-arcs.gif`)
+- **Choropleth Countries** — GDP-per-capita coloring with clientside hover highlight (`assets/examples/choropleth.png`)
+- **Large Dataset via data_url** — Browser-fetched GeoJSON with summary hover payloads (`assets/examples/large-dataset.gif`)
+- **Airline Routes** — OpenFlights-derived routes with hover highlighting (`assets/examples/airline-routes.png`)
+- **Day Night Cycle** — First-class day/night shader mode (`assets/examples/day-night-cycle.gif`)
+- **Clouds** — Rotating transparent cloud shell (`assets/examples/clouds.gif`)
+- **Situation Room** — Camera-aware tethered HTML overlays for briefing-style scenes (`assets/examples/situation-room.png`)
+
+## Run the interactive gallery
+
+```bash
+cd dash_globe
+python usage.py
+```
+
+Source: [usage.py](https://github.com/jeffgallini/dash-globe/blob/master/dash_globe/usage.py)
+
+See also: [API reference](./api.md), [Getting started](./getting-started.md), [llms.txt](./llms.txt).
diff --git a/docs/getting-started.html b/docs/getting-started.html
@@ -5,18 +5,22 @@
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>Getting Started · Dash Globe</title>
   <link rel="stylesheet" href="assets/site.css" />
+  <link rel="alternate" type="text/markdown" href="getting-started.md" />
+  <link rel="describedby" href="llms.txt" />
 </head>
 <body>
   <header class="site-header">
     <div class="wrap">
       <a class="brand" href="index.html">
-        <span class="brand-mark" aria-hidden="true">🌐</span>
+        <span class="brand-mark" aria-hidden="true"></span>
         <span>Dash Globe</span>
       </a>
       <nav class="nav">
         <a href="index.html">Home</a>
         <a class="active" href="getting-started.html">Getting Started</a>
+        <a href="api.html">API</a>
         <a href="examples.html">Examples</a>
+        <a href="llms.txt">llms.txt</a>
         <a href="https://github.com/jeffgallini/dash-globe">GitHub</a>
         <a href="https://pypi.org/project/dash-globe/">PyPI</a>
       </nav>
@@ -99,7 +103,7 @@ <h2>Local docs gallery</h2>
   <footer class="footer">
     <div class="wrap">
       <div>Dash Globe v1.0.0</div>
-      <div><a href="examples.html">Browse examples →</a></div>
+      <div><a href="api.html">API reference →</a></div>
     </div>
   </footer>
 </body>