Merge pull request #2 from opensource-observer/feat/static-notebook-export

Turn DDP into a static web app

Author: ccerv1

.github/workflows/deploy.yml

@@ -0,0 +1,50 @@
+name: Build and deploy
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+  workflow_call:
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - uses: astral-sh/setup-uv@v4
+      - run: uv python install 3.13
+
+      - name: Install Python deps
+        run: uv sync
+
+      - name: Check if notebooks changed
+        id: changed
+        run: |
+          git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -q '^notebooks/' \
+            && echo "notebooks=true" >> $GITHUB_OUTPUT \
+            || echo "notebooks=false" >> $GITHUB_OUTPUT
+
+      - name: Export notebooks
+        if: steps.changed.outputs.notebooks == 'true' || github.event_name != 'push'
+        env:
+          OSO_API_KEY: ${{ secrets.OSO_API_KEY }}
+        run: uv run python scripts/export_notebooks.py
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+          cache-dependency-path: app/pnpm-lock.yaml
+
+      - name: Install Node deps
+        run: cd app && pnpm install
+
+      - name: Build Next.js
+        run: cd app && pnpm build

.github/workflows/refresh-data.yml

@@ -0,0 +1,11 @@
+name: Weekly data refresh
+
+on:
+  schedule:
+    - cron: '0 3 * * 0'  # Sunday 3am UTC
+  workflow_dispatch:
+
+jobs:
+  refresh:
+    uses: ./.github/workflows/deploy.yml
+    secrets: inherit

.gitignore

@@ -14,11 +14,14 @@ __pycache__/
 # --- Environment variables ---
 .env
 .env.local
+app/.env.*
 
 # --- Next.js (app/) ---
 app/.next/
 app/out/
 app/node_modules/
+app/public/notebooks/
+app/public/data/
 
 # --- OS ---
 .DS_Store

README.md

@@ -13,8 +13,11 @@ cp .env.example .env
 uv sync
 cd app && pnpm install && cd ..
 
-# 3. Start
-cd app && pnpm dev:all
+# 3. Export notebooks to static HTML
+cd app && pnpm export:notebooks && cd ..
+
+# 4. Start the dev server
+cd app && pnpm dev
 ```
 
 Open http://localhost:3000.
@@ -30,7 +33,6 @@ Open http://localhost:3000.
 ```
 ddp/
 ├── notebooks/              # Marimo notebooks (.py)
-│   ├── home.py
 │   ├── quick-start.py
 │   ├── publications.py
 │   ├── agent-guide.py
@@ -39,17 +41,20 @@ ddp/
 │   │   ├── models/         # Ecosystems, Repositories, Developers, Commits, Events, Timeseries Metrics
 │   │   └── metric-definitions/  # Activity, Alignment, Lifecycle, Retention
 │   └── insights/           # 2025 Developer Trends, Lifecycle, Speedrun Ethereum, DeFi Journeys, Retention
+├── scripts/
+│   └── export_notebooks.py # Exports notebooks to static HTML
 ├── app/                    # Next.js app (UI shell)
 │   ├── app/                # Pages (App Router)
-│   └── components/         # Sidebar, MarimoIframe
-├── serve_notebooks.py      # Marimo ASGI server (port 8000)
+│   ├── components/         # Sidebar, MarimoIframe
+│   └── public/notebooks/   # Exported HTML (generated, gitignored)
 └── pyproject.toml
 ```
 
 ## How it works
 
-- **Marimo server** (`localhost:8000`) — runs notebook kernels via `serve_notebooks.py`
-- **Next.js app** (`localhost:3000`) — navigation shell that embeds notebooks in iframes
+- **Export step** — `scripts/export_notebooks.py` runs `marimo export html` on each notebook, writing static HTML to `app/public/notebooks/`
+- **Next.js app** (`localhost:3000`) — navigation shell that serves the exported HTML via `MarimoIframe`
+- **CI** — the [deploy workflow](.github/workflows/deploy.yml) exports notebooks and builds the site on push to `main`. A [weekly refresh](.github/workflows/refresh-data.yml) re-exports to pick up fresh data.
 
 Each page in the Next.js app is a thin wrapper around a `MarimoIframe` component:
 
@@ -62,6 +67,7 @@ Each page in the Next.js app is a thin wrapper around a `MarimoIframe` component
 1. Create `notebooks/<category>/<name>.py` using the standard template below
 2. Add a page at `app/app/<category>/<name>/page.tsx`
 3. Add a nav entry to `app/components/Sidebar.tsx`
+4. Run `cd app && pnpm export:notebooks` to generate the HTML
 
 ### Notebook template
 
@@ -88,22 +94,8 @@ if __name__ == "__main__":
 
 For detailed notebook conventions, see [`notebooks/claude.md`](notebooks/claude.md).
 
-## Running servers separately
-
-```bash
-# Terminal 1 — Marimo
-uv run python serve_notebooks.py
-
-# Terminal 2 — Next.js
-cd app && pnpm dev
-```
-
-Notebooks are served at `http://localhost:8000/notebooks/<name>` — Marimo must be running for iframes to render.
-
 ## Configuration
 
 | Variable | Description |
 |----------|-------------|
 | `OSO_API_KEY` | Required. OSO data warehouse access key. |
-
-The Marimo port defaults to `8000`. To change it, update `serve_notebooks.py` and the `marimoPort` prop on `MarimoIframe` in any relevant pages.

app/app/insights/defi-developer-journeys/page.tsx

@@ -1,9 +1,5 @@
+'use client';
 import MarimoIframe from '@/components/MarimoIframe';
-
 export default function DefiDeveloperJourneys() {
-  return (
-    <div className="h-full w-full">
-      <MarimoIframe notebookName="notebooks/insights/defi-developer-journeys" />
-    </div>
-  );
+  return <MarimoIframe notebookName="notebooks/insights/defi-developer-journeys" />;
 }

app/app/insights/developer-lifecycle/page.tsx

@@ -1,9 +1,5 @@
+'use client';
 import MarimoIframe from '@/components/MarimoIframe';
-
 export default function DeveloperLifecycle() {
-  return (
-    <div className="h-full w-full">
-      <MarimoIframe notebookName="notebooks/insights/developer-lifecycle" />
-    </div>
-  );
+  return <MarimoIframe notebookName="notebooks/insights/developer-lifecycle" />;
 }

app/app/insights/developer-report-2025/page.tsx

@@ -1,9 +1,5 @@
+'use client';
 import MarimoIframe from '@/components/MarimoIframe';
-
 export default function DeveloperReport2025() {
-  return (
-    <div className="h-full w-full">
-      <MarimoIframe notebookName="notebooks/insights/developer-report-2025" />
-    </div>
-  );
+  return <MarimoIframe notebookName="notebooks/insights/developer-report-2025" />;
 }

app/app/insights/developer-retention/page.tsx

@@ -1,9 +1,5 @@
+'use client';
 import MarimoIframe from '@/components/MarimoIframe';
-
 export default function DeveloperRetention() {
-  return (
-    <div className="h-full w-full">
-      <MarimoIframe notebookName="notebooks/insights/developer-retention" />
-    </div>
-  );
+  return <MarimoIframe notebookName="notebooks/insights/developer-retention" />;
 }

app/app/insights/speedrun-ethereum/page.tsx

@@ -1,9 +1,5 @@
+'use client';
 import MarimoIframe from '@/components/MarimoIframe';
-
 export default function SpeedrunEthereum() {
-  return (
-    <div className="h-full w-full">
-      <MarimoIframe notebookName="notebooks/insights/speedrun-ethereum" />
-    </div>
-  );
+  return <MarimoIframe notebookName="notebooks/insights/speedrun-ethereum" />;
 }

app/app/layout.tsx

@@ -17,7 +17,7 @@ export default function RootLayout({
       <body className="bg-white">
         <div className="flex h-screen overflow-hidden">
           <Sidebar />
-          <main className="flex-1 flex flex-col overflow-hidden bg-white">
+          <main className="flex-1 flex flex-col overflow-y-auto bg-white">
             {children}
           </main>
         </div>