feat: rich notebook previews through OpenGraph metadata (#8097)

## 📝 Summary

Adds notebook-level OpenGraph metadata (PEP 723 +
[Next.js-inspired](https://nextjs.org/docs/app/api-reference/functions/generate-metadata)
optional generator hook) with thumbnail generation plumbing. As a first
use case, wired it up to improve gallery cards in `marimo run <dir>`.

Follow-up of #8056.

## 🔍 Description of Changes

- Introduced `OpenGraphMetadata` for notebooks via PEP 723:
`[tool.marimo.opengraph]` with `title`, `description`, `image`, and
optional `generator`
  - `image` supports either an HTTPS URL or a notebook-relative path
- Added Next.js-style merge semantics for generators: static PEP 723
fields are the base; generator can override only the fields it returns
- Added a canonical thumbnail endpoint: `GET
/api/home/thumbnail?file=...`
  - redirects to HTTPS images
- serves notebook-relative images only from the notebook’s `__marimo__/`
directory
  - falls back to a branded placeholder SVG when no image exists
- Inject OG tags into notebook pages (`og:title`, `og:description`,
`og:image`)
- Gallery cards now prefer `FileInfo.opengraph`
(title/description/image) and fall back to the existing title-casing
behavior
- Added `marimo tools thumbnails generate ...` to write thumbnails to
`__marimo__/assets/<stem>/opengraph.png`
  - default is `--no-execute` (fast; no cell outputs)
  - opt-in `--execute` to include outputs
  - opt-in `--sandbox` (only applies with `--execute`)

## 📸 Thumbnails

> in the examples below `marimo-team/learn` is a local clone of
https://github.com/marimo-team/learn

### Auto-generated thumbnails without `playwright`

No file gets written to disk. The `/thumbnail` API endpoint calls
`DEFAULT_OPENGRAPH_PLACEHOLDER_IMAGE_GENERATOR` to construct an SVG
dynamically and serves it.

<img width="1111" height="1314" alt="Screenshot 2026-02-03 at 14 36 25"
src="https://github.com/user-attachments/assets/73cdaa8c-ba4a-4c4e-a27d-cb48163b17b5"
/>

### Auto-generated thumbnails with `playwright`, but without notebook
execution

Renders code blocks without outputs, similar to Observable, as suggested
by @manzt.

```
 marimo tools thumbnails generate marimo-team/learn
 marimo run marimo-team/learn
```

<img width="1111" height="1314" alt="Screenshot 2026-02-03 at 14 40 50"
src="https://github.com/user-attachments/assets/d02611bd-e094-4031-ac7b-fec82330960a"
/>

### Auto-generated thumbnails with `playwright`, with sandboxed notebook
execution for cell outputs

> If you have generated thumbnails, pass ` --overwrite` to `marimo tools
thumbnails` to ensure they get replaced.

```
marimo tools thumbnails generate marimo-team/learn --execute --sandbox
marimo run marimo-team/learn  
```

<img width="1111" height="1314" alt="Screenshot 2026-02-03 at 14 49 52"
src="https://github.com/user-attachments/assets/9d6e0ea4-3845-436f-9ab5-9defd274cdc6"
/>

## ⚡️ Generators

Users can define custom functions to return OG metadata based on bespoke
logic.

Below an example of a notebook (1) defining `generator =
"generate_opengraph"` in PEP 723 then (2) implementing `def
generate_opengraph(context, parent):` as `@app.function` to return the
metadata dynamically, yielding a custom card from with image from
https://placehold.co/1200x630/png.

<img width="374" height="345" alt="Screenshot 2026-02-03 at 14 58 42"
src="https://github.com/user-attachments/assets/478af1c1-e6f3-4fc7-a79f-e604f39b591d"
/>

```python
# /// script
# dependencies = [
#     "marimo>=0.19.0",
#     "pyzmq>=27.1.0",
# ]
# [tool.marimo.opengraph]
# description = "The description is static, but the title and image have been computed dynamically using a generator function defined within the notebook."
# generator = "generate_opengraph"
# ///

import marimo

__generated_with = "0.19.7"
app = marimo.App(width="medium")


@app.cell(hide_code=True)
def _(mo):
    mo.md("""
    # Dynamic OpenGraph Image
    """)
    return


@app.function
def generate_opengraph(context, parent):
    import datetime as dt
    from pathlib import Path
    from urllib.parse import quote_plus

    # Merge behavior: we return `title` and `image`, so static PEP 723 description
    # remains intact, as `description` is already present in `parent`
    label = quote_plus(dt.datetime.now().isoformat())
    return {
        "title": f"Dynamic OpenGraph",
        "image": f"https://placehold.co/1200x630/png?text={label}"
    }


@app.cell(hide_code=True)
def _():
    import marimo as mo
    return (mo,)


if __name__ == "__main__":
    app.run()
```

Author: peter-gy

frontend/src/components/pages/gallery-page.tsx

@@ -33,6 +33,15 @@ const tabTarget = (path: string): string => {
   return `${getSessionId()}-${encodeURIComponent(path)}`;
 };
 
+const isHttpsUrl = (value: string): boolean => {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:";
+  } catch {
+    return false;
+  }
+};
+
 const SEARCH_THRESHOLD = 10;
 
 const GalleryPage: React.FC = () => {
@@ -43,28 +52,39 @@ const GalleryPage: React.FC = () => {
     [],
   );
   const workspace = response.data;
-  const files = workspace?.files ?? [];
-  const root = workspace?.root ?? "";
 
   const formattedFiles = useMemo(() => {
+    const files = workspace?.files ?? [];
+    const root = workspace?.root ?? "";
     return files
       .filter((file) => !file.isDirectory)
       .map((file) => {
         const relativePath =
           root && Paths.isAbsolute(file.path) && file.path.startsWith(root)
             ? Paths.rest(file.path, root)
             : file.path;
-        const title = titleCase(Paths.basename(relativePath));
+        const title =
+          file.opengraph?.title ?? titleCase(Paths.basename(relativePath));
         const subtitle = titleCase(Paths.dirname(relativePath));
+        const description = file.opengraph?.description ?? "";
+        const opengraphImage = file.opengraph?.image;
+        const thumbnailUrl =
+          opengraphImage && isHttpsUrl(opengraphImage)
+            ? opengraphImage
+            : asURL(
+                `/og/thumbnail?file=${encodeURIComponent(relativePath)}`,
+              ).toString();
         return {
           ...file,
           relativePath,
           title,
           subtitle,
+          description,
+          thumbnailUrl,
         };
       })
       .sort((a, b) => a.relativePath.localeCompare(b.relativePath));
-  }, [files, root]);
+  }, [workspace?.files, workspace?.root]);
 
   const filteredFiles = useMemo(() => {
     if (!searchQuery) {
@@ -130,8 +150,14 @@ const GalleryPage: React.FC = () => {
                     target={tabTarget(file.path)}
                     className="no-underline"
                   >
-                    <Card className="h-full hover:bg-accent/20 transition-colors">
-                      <CardContent className="p-6">
+                    <Card className="h-full overflow-hidden hover:bg-accent/20 transition-colors">
+                      <img
+                        src={file.thumbnailUrl}
+                        alt={file.title}
+                        loading="lazy"
+                        className="w-full aspect-1200/630 object-cover border-b border-border/60"
+                      />
+                      <CardContent className="p-6 pt-4">
                         <div className="flex flex-col gap-1">
                           {file.subtitle && (
                             <div className="text-sm font-semibold text-muted-foreground">
@@ -141,6 +167,11 @@ const GalleryPage: React.FC = () => {
                           <div className="text-lg font-medium">
                             {file.title}
                           </div>
+                          {file.description && (
+                            <div className="text-sm text-muted-foreground line-clamp-3 mt-1">
+                              {file.description}
+                            </div>
+                          )}
                         </div>
                       </CardContent>
                     </Card>

marimo/_cli/cli.py

@@ -27,6 +27,7 @@
 from marimo._cli.run_docker import (
     prompt_run_in_docker_container,
 )
+from marimo._cli.tools.commands import tools
 from marimo._cli.upgrade import check_for_updates, print_latest_version
 from marimo._cli.utils import (
     check_app_correctness,
@@ -1476,3 +1477,4 @@ def check(
 main.add_command(export)
 main.add_command(config)
 main.add_command(development)
+main.add_command(tools)

marimo/_cli/development/commands.py

@@ -28,6 +28,7 @@ def _generate_server_api_schema() -> dict[str, Any]:
     import marimo._data.models as data
     import marimo._messaging.errors as errors
     import marimo._messaging.notification as notifications
+    import marimo._metadata.opengraph as opengraph
     import marimo._runtime.commands as commands
     import marimo._secrets.models as secrets_models
     import marimo._server.models.completion as completion
@@ -132,6 +133,7 @@ def _generate_server_api_schema() -> dict[str, Any]:
         ToolDefinition,
         # Sub components
         home.MarimoFile,
+        opengraph.OpenGraphMetadata,
         files.FileInfo,
         commands.ExecuteCellCommand,
         snippets.SnippetSection,

marimo/_cli/tools/__init__.py

@@ -0,0 +1 @@
+# Copyright 2026 Marimo. All rights reserved.

marimo/_cli/tools/commands.py

@@ -0,0 +1,14 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import click
+
+from marimo._cli.tools.thumbnails import thumbnails
+
+
+@click.group(help="Utilities for marimo notebooks.")
+def tools() -> None:
+    pass
+
+
+tools.add_command(thumbnails)