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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
docs: gallery + OpenGraph preview docs (#8122)
Péter Gyarmati669b894196b2
diff --git a/docs/guides/apps.md b/docs/guides/apps.mdindex 5f4ceac152..3c6a814227 100644--- a/docs/guides/apps.md+++ b/docs/guides/apps.md@@ -17,6 +17,17 @@ marimo run notebook.pyView 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).+## LayoutWhile editing a notebook with `marimo edit`, you can preview the notebookdiff --git a/docs/guides/configuration/html_head.md b/docs/guides/configuration/html_head.mdindex 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**```htmldiff --git a/docs/guides/publishing/index.md b/docs/guides/publishing/index.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.ymlindex 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