Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

docs: gallery + OpenGraph preview docs (#8122)

Péter Gyarmati669b894196b2
diff --git a/docs/guides/apps.md b/docs/guides/apps.md
index 5f4ceac152..3c6a814227 100644
--- a/docs/guides/apps.md
+++ b/docs/guides/apps.md
@@ -17,6 +17,17 @@ marimo run notebook.py
View the [CLI documentation](../cli.md#marimo-run) for more details.
+### Gallery
+
+You can run multiple notebooks (or a directory of notebooks) as a gallery:
+
+```bash
+marimo run folder/
+marimo run notebook_a.py notebook_b.py folder/
+```
+
+This shows a page with one card per notebook. Cards can use notebook OpenGraph metadata for the title, description, and thumbnail image. Configure [OpenGraph previews](publishing/opengraph.md) and optionally generate images with [Thumbnails](publishing/thumbnails.md).
+
## Layout
While editing a notebook with `marimo edit`, you can preview the notebook
diff --git a/docs/guides/configuration/html_head.md b/docs/guides/configuration/html_head.md
index b806eae5a1..205d56d4cf 100644
--- a/docs/guides/configuration/html_head.md
+++ b/docs/guides/configuration/html_head.md
@@ -51,6 +51,10 @@ Here are some common use cases for custom HTML head content:
<meta property="og:image" content="https://example.com/thumbnail.jpg" />
```
+!!! tip "OpenGraph previews"
+
+ For common OpenGraph fields (title, description, image), you can also use notebook OpenGraph metadata in script metadata. See [OpenGraph previews](../publishing/opengraph.md).
+
4. **External Scripts and Libraries**
```html
diff --git a/docs/guides/publishing/index.md b/docs/guides/publishing/index.md
index d82936cc97..19c17a9c59 100644
--- a/docs/guides/publishing/index.md
+++ b/docs/guides/publishing/index.md
@@ -25,5 +25,7 @@ This guide provides an overview of the various ways to publish marimo notebooks.
| [Self-host WebAssembly notebooks](self_host_wasm.md) | Self-hosting interactive WebAssembly (HTML export) notebooks |
| [Online playground](playground.md) | Share links to notebooks using our online playground |
| [View notebooks on GitHub](view_outputs_on_github.md) | Viewing notebook outputs on GitHub |
+| [OpenGraph previews](opengraph.md) | Configure titles, descriptions, and thumbnails for link previews |
+| [Thumbnails](thumbnails.md) | Generate thumbnail images for OpenGraph previews and galleries |
| [Deploy on a backend](deploy.md) | Deploying notebooks on backends |
| [With Quarto](quarto.md) | Publish reactive websites with Quarto from markdown |
diff --git a/docs/guides/publishing/opengraph.md b/docs/guides/publishing/opengraph.md
new file mode 100644
index 0000000000..52fcede0ff
--- /dev/null
+++ b/docs/guides/publishing/opengraph.md
@@ -0,0 +1,116 @@
+# OpenGraph previews
+
+marimo can attach OpenGraph metadata to notebooks for:
+
+- previews in the `marimo run <directory>` [gallery](../apps.md#gallery-mode)
+- link previews (OpenGraph tags in the notebook HTML)
+
+You configure this metadata in your notebook file using inline script metadata (PEP 723), under `[tool.marimo.opengraph]`.
+
+## Configure metadata
+
+Add an `[tool.marimo.opengraph]` section to your script metadata:
+
+```python
+# /// script
+# [tool.marimo.opengraph]
+# title = "My notebook"
+# description = "An interactive marimo app."
+# ///
+```
+
+Available fields:
+
+- `title`: Title used in previews (defaults to a title-cased filename).
+- `description`: Short description shown in previews.
+- `image`: Optional thumbnail image. Must be either:
+ - an HTTPS URL, or
+ - a notebook-relative path under `__marimo__/` (for example, `__marimo__/assets/my_notebook/opengraph.png`).
+
+If you generate thumbnails to the default location (see below), you typically do not need to set `image`: marimo will automatically use `__marimo__/assets/<notebook_stem>/opengraph.png` when it exists.
+
+!!! note "Relative image paths"
+
+ For security, marimo only serves notebook-relative `image` paths from the notebook's `__marimo__/` directory.
+
+## Thumbnails
+
+If you do not provide an `image`, marimo can still serve a deterministic placeholder thumbnail. If a screenshot-based thumbnail exists at the default location, marimo will automatically use it.
+
+The default thumbnail location is:
+
+```
+__marimo__/assets/<notebook_stem>/opengraph.png
+```
+
+To generate these thumbnails, use:
+
+```bash
+marimo tools thumbnails generate notebook.py
+marimo tools thumbnails generate folder/
+```
+
+For execution and sandbox options (and for Playwright installation instructions), see [Thumbnails](thumbnails.md).
+
+## Dynamic metadata
+
+For dynamic previews, you can provide a generator function in script metadata. Generators must be [top-level functions](../reusing_functions.md) (decorated with `@app.function`) and cannot depend on values defined in regular cells, so that they can be safely executed in the marimo CLI without running the whole notebook.
+
+In script metadata, point `generator` at the name of a function defined in the notebook:
+
+```python
+# /// script
+# [tool.marimo.opengraph]
+# description = "This description is static."
+# generator = "generate_opengraph"
+# ///
+```
+
+Then define the generator in a notebook cell:
+
+/// marimo-embed
+```python
+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 the static `description` stays intact (it's already in `parent`).
+ stem = Path(context.filepath).stem
+ label = quote_plus(f"{stem} {dt.datetime.now().isoformat()}")
+ title = f"{parent.title} (Dynamic)" if parent.title else "Dynamic OpenGraph"
+ return {
+ "title": title,
+ "image": f"https://placehold.co/1200x630/png?text={label}",
+ }
+```
+///
+
+The generator return value is merged on top of the resolved "parent" metadata (declared fields + defaults). Any fields not returned by the generator are inherited from `parent`.
+
+### Generator signatures
+
+The generator may accept 0, 1, or 2 positional arguments:
+
+- `generate_opengraph()`
+- `generate_opengraph(context)`
+- `generate_opengraph(context, parent)`
+
+Type hints:
+
+- `context`: `marimo._metadata.opengraph.OpenGraphContext`
+- `parent`: `marimo._metadata.opengraph.OpenGraphMetadata`
+
+`context` is an object with useful runtime information:
+
+- `context.filepath`: absolute path to the notebook
+- `context.file_key`: file router key (often a workspace-relative path)
+- `context.base_url`: server base URL (when running with `marimo run`)
+- `context.mode`: `"run"` or `"edit"`
+
+The generator may return:
+
+- an `OpenGraphMetadata` instance
+- a `dict` with any of `title`, `description`, and `image`
+- `None` (to leave the parent metadata unchanged)
diff --git a/docs/guides/publishing/thumbnails.md b/docs/guides/publishing/thumbnails.md
new file mode 100644
index 0000000000..954d2fb79f
--- /dev/null
+++ b/docs/guides/publishing/thumbnails.md
@@ -0,0 +1,117 @@
+# Thumbnails
+
+Generate screenshot-based thumbnail images for notebooks, used by [OpenGraph previews](opengraph.md) and cards in [gallery mode](../apps.md#gallery-mode).
+
+```bash
+marimo export thumbnail generate notebook.py
+
+## Output location
+
+By default, thumbnails are written to:
+
+```
+<notebook_dir>/__marimo__/assets/<notebook_stem>/opengraph.png
+```
+
+This is the default OpenGraph thumbnail path used by [OpenGraph previews](opengraph.md).
+
+## Requirements
+
+!!! note "Requires Playwright"
+
+ Thumbnail generation uses Playwright and Chromium:
+
+ ```bash
+ python -m pip install playwright
+ python -m playwright install chromium
+ ```
+
+## Generate thumbnails
+
+You can generate a thumbnail for a single notebook:
+
+```bash
+marimo tools thumbnails generate notebook.py
+```
+
+Or generate thumbnails for all notebooks in a directory:
+
+```bash
+marimo tools thumbnails generate folder/
+```
+
+When you pass a directory, marimo scans it for marimo notebooks and skips non-notebook files (for example `README.md`).
+
+## Execution modes
+
+By default, thumbnails are generated without executing the notebook (fast; no outputs). You can opt into execution if you want outputs included.
+
+=== "No execution (default)"
+
+ ```bash
+ marimo tools thumbnails generate notebook.py
+ ```
+
+=== "Execute notebook"
+
+ ```bash
+ marimo tools thumbnails generate notebook.py --execute
+ ```
+
+=== "Execute in a sandbox"
+
+ ```bash
+ marimo tools thumbnails generate notebook.py --execute --sandbox
+ ```
+
+ !!! note "Requires uv"
+
+ `--sandbox` runs the notebook in an isolated environment and installs dependencies from inline script metadata (PEP 723). See [Inlining dependencies](../package_management/inlining_dependencies.md).
+
+!!! note "Sandbox only applies with execution"
+
+ `--sandbox` requires `--execute`. In `--no-execute` mode, marimo does not run the notebook, so there are no dependencies to install.
+
+!!! tip "Including code"
+
+ In `--no-execute` mode, thumbnails always include code. When using `--execute`, add `--include-code` to show code alongside outputs.
+
+## Overwriting and custom output paths
+
+If a thumbnail already exists, marimo will skip it by default. To replace existing thumbnails:
+
+```bash
+marimo tools thumbnails generate notebook.py --overwrite
+```
+
+To write a thumbnail to a specific filename, use `--output` (single notebook only):
+
+```bash
+marimo tools thumbnails generate notebook.py --output thumbnail.png
+```
+
+## Tuning quality
+
+For OpenGraph previews, the default viewport size is 1200x630. marimo also uses a default `--scale 2` so thumbnails are crisp at typical OpenGraph resolutions.
+
+To increase output resolution, increase `--scale` (max 4):
+
+```bash
+marimo tools thumbnails generate notebook.py --scale 3
+```
+
+If thumbnails appear blank or partially rendered, increase `--timeout-ms` to wait longer before the screenshot:
+
+```bash
+marimo tools thumbnails generate notebook.py --timeout-ms 3000
+```
+
+## Passing arguments to notebooks
+
+To pass CLI args through to the notebook, separate them with `--`:
+
+```bash
+marimo tools thumbnails generate notebook.py -- --foo 123
+```
+
+For more on passing values to notebooks, see [Command Line Arguments](../../api/cli_args.md).
diff --git a/mkdocs.yml b/mkdocs.yml
index 783aed547f..9380d49c71 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -137,6 +137,8 @@ nav:
- Embedding: guides/publishing/embedding.md
- From code snippets: guides/publishing/from_code_snippets.md
- From GitHub: guides/publishing/from_github.md
+ - OpenGraph previews: guides/publishing/opengraph.md
+ - Thumbnails: guides/publishing/thumbnails.md
- Static sites:
- GitHub Pages: guides/publishing/github_pages.md
- Cloudflare: guides/publishing/cloudflare.md