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: marimo glance (#10282)

Akshay Agrawal86f90f010326
diff --git a/docs/_static/docs-app-config.png b/docs/_static/docs-app-config.png
index c19a597337..b74e93c1ab 100644
Binary files a/docs/_static/docs-app-config.png and b/docs/_static/docs-app-config.png differ
diff --git a/docs/_static/molab-copy-embed-iframe.png b/docs/_static/molab-copy-embed-iframe.png
new file mode 100644
index 0000000000..0b3e88569b
Binary files /dev/null and b/docs/_static/molab-copy-embed-iframe.png differ
diff --git a/docs/_static/molab-wasm-preview.png b/docs/_static/molab-wasm-preview.png
new file mode 100644
index 0000000000..425f798a9f
Binary files /dev/null and b/docs/_static/molab-wasm-preview.png differ
diff --git a/docs/faq.md b/docs/faq.md
index b6ea801d09..0c5ce66fd7 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -68,8 +68,8 @@ value. This is difficult to get working in Jupyter notebooks.
marimo notebooks can be executed as Python scripts from the command-line (since
they're stored as `.py` files). In contrast, this requires extra steps to
do for Jupyter, such as copying and pasting the code out or using external
-frameworks. We also let you import symbols (functions, classes) defined in a
-marimo notebook into other Python programs/notebooks, something you can't
+frameworks. We also let you import symbols (functions, classes) defined in a
+marimo notebook into other Python programs/notebooks, something you can't
easily do with Jupyter.
**Shareability.**
@@ -567,6 +567,21 @@ notebook to an `ipynb` file, or export to `HTML`:
1. export to ipynb: `marimo export ipynb my_notebook.py -o my_notebook.ipynb --include-outputs`
2. export to HTML: `marimo export html my_notebook.py -o my_notebook.html`
+<a name="faq-github-preview"></a>
+
+### How do I preview notebooks on GitHub?
+
+Here are a few ways to preview notebooks on GitHub:
+
+1. Export notebooks to ipynb.
+2. Install the marimo glance browser extension for
+[Chrome](https://chromewebstore.google.com/detail/marimo-glance/emnkplkdlpojjembfbkdagibhmippjfg) or
+[Firefox](https://addons.mozilla.org/en-US/firefox/addon/marimo-glance/), which
+lets you replace a notebook's raw Python source on GitHub or GitLab with an
+interactive notebook in one click. The marimo glance extension only works for notebooks compatible with [WebAssembly](guides/wasm.md).
+3. Use [molab's built-in GitHub previewer](guides/molab.md#mirror-notebooks-from-github).
+
+
<a name="faq-app-deploy"></a>
### How do I deploy apps?
diff --git a/docs/guides/coming_from/jupyter.md b/docs/guides/coming_from/jupyter.md
index bcad395c85..0dd0702feb 100644
--- a/docs/guides/coming_from/jupyter.md
+++ b/docs/guides/coming_from/jupyter.md
@@ -125,8 +125,8 @@ augmented_df = df
augmented_df["another_column"] = [3, 4]
```
-To learn how to write Pandas/Polars code in a functional style,
-which is more amenable to marimo's execution model, check out
+To learn how to write Pandas/Polars code in a functional style,
+which is more amenable to marimo's execution model, check out
[this YouTube video](https://youtu.be/J0PJpdU7c4g).
## marimo's file format
@@ -136,12 +136,26 @@ with git, [execute them as scripts](../scripts.md), and import named
cells into other Python files. However, it does mean that your notebook outputs
(e.g., plots) are not stored in the file.
-If you'd like to keep a visual record of your notebook work, [enable
+### Store notebook outputs
+
+To keep a visual record of your notebook work, [enable
the "Auto-download as HTML/IPYNB" setting](../configuration/index.md), which will
-periodically snapshot your notebook as HTML or IPYNB to a `__marimo__` folder in the
-notebook directory.
+periodically snapshot your notebook as HTML or ipynb to a `__marimo__` folder
+in the notebook directory. You can also export to ipynb from marimo's CLI,
+using the `marimo export` command.
+
+### Preview notebook outputs on GitHub
+
+Check in exported ipynb files to version control to view notebook outputs on GitHub.
+
+You can also install the marimo glance
+[Chrome](https://chromewebstore.google.com/detail/marimo-glance/emnkplkdlpojjembfbkdagibhmippjfg)
+or [Firefox](https://addons.mozilla.org/en-US/firefox/addon/marimo-glance/)
+extensions to render live interactive previews of notebooks on GitHub, which
+can work well for inexpensive and self-contained notebooks. (The extension renders notebooks
+[with WebAssembly](../wasm.md), so not all notebooks will work.)
-### Converting Jupyter notebooks to marimo notebooks
+### Convert Jupyter notebooks to marimo notebooks
Convert Jupyter notebooks to marimo notebooks at the command-line:
@@ -149,7 +163,7 @@ Convert Jupyter notebooks to marimo notebooks at the command-line:
marimo convert your_notebook.ipynb -o your_notebook.py
```
-### Converting Python scripts to marimo notebooks
+### Convert Python scripts to marimo notebooks
marimo can also convert regular Python scripts to marimo notebooks:
@@ -167,7 +181,7 @@ For py:percent conversion with uv:
uvx --with=jupytext marimo convert your_script.py -o your_notebook.py
```
-### Exporting marimo notebooks to Jupyter notebooks
+### Export marimo notebooks to Jupyter notebooks
Export to an `ipynb` file with
diff --git a/docs/guides/configuration/index.md b/docs/guides/configuration/index.md
index fe91a9e401..68ba84d629 100644
--- a/docs/guides/configuration/index.md
+++ b/docs/guides/configuration/index.md
@@ -1,14 +1,16 @@
# Configuration
-marimo offers two types of configuration: User Configuration and App
-Configuration. Both can be easily managed through the Settings menu in the
-marimo editor.
+marimo offers two types of configuration: User Settings, which apply globally
+to all your notebooks, and Notebook Settings, which apply to a single notebook.
+Both can be configured in the marimo editor.
-<img align="right" src="/_static/docs-app-config.png" width="300px"/>
+<img align="right" src="/_static/docs-app-config.png" alt="Notebook settings dialog showing display, data, custom files, and exporting options" width="420px"/>
-## App Configuration
+## Notebook settings
-App Configuration is specific to each notebook and is stored in the `notebook.py` file. This allows you to customize various aspects of your notebook, including:
+Notebook settings are specific to each notebook and are stored in the
+`notebook.py` file. This allows you to customize various aspects of your
+notebook, including:
- Notebook width
- Notebook title
@@ -20,15 +22,16 @@ Configure these settings through the notebook menu (⚙️) in the top-right cor
<br clear="left"/>
-## User Configuration
+## User settings
-User Configuration applies globally across all marimo notebooks and is stored
+User settings apply globally across all marimo notebooks and are stored
in a `$XDG_CONFIG_HOME/marimo/marimo.toml` file.
-While you can edit the `$XDG_CONFIG_HOME/marimo/marimo.toml` file directly, we recommend using the
-marimo UI for a more user-friendly experience.
-
-<video controls width="100%" height="100%" align="center" src="/_static/docs-user-config.mp4"> </video>
+While you can edit the `$XDG_CONFIG_HOME/marimo/marimo.toml` file directly, we
+recommend using the marimo UI for a more user-friendly experience. Click the
+"User settings" button in the bottom of the notebook settings menu to open
+configuration UI, or hit `Cmd/Ctrl + k` to open the command palette and type
+`"User settings"`.
You can customize the following settings:
@@ -94,7 +97,7 @@ You can override any user configuration setting in this way. To find these setti
!!! note "Overridden settings"
Settings overridden in `pyproject.toml` or script metadata cannot be changed through the marimo editor's settings menu. Any changes made to overridden settings in the editor will not take effect.
-### Script Metadata Configuration
+### Script metadata configuration
You can also configure marimo settings directly in your notebook files using script metadata (PEP 723). Add a `script` block at the top of your notebook:
@@ -114,7 +117,7 @@ You can also configure marimo settings directly in your notebook files using scr
**Script config > pyproject.toml config > user config**
-## Environment Variables
+## Environment variables
marimo supports the following environment variables for advanced configuration:
diff --git a/docs/guides/molab.md b/docs/guides/molab.md
index 2a1b3b26ca..8169de6282 100644
--- a/docs/guides/molab.md
+++ b/docs/guides/molab.md
@@ -107,7 +107,9 @@ workspace.
> See our [gallery examples](https://github.com/marimo-team/gallery-examples) repository for best practices on previewing notebooks from GitHub.
-By default, notebooks mirrored from GitHub show a static preview of the notebook. (The notebook dropdown in the app header allows you to toggle to interactive previews with a running notebook.)
+By default, notebooks mirrored from GitHub show a static preview of the
+notebook; from the static preview page, users can start the notebook on an ephemeral server
+or fork it into their workspace with a single click.
In order for your static preview to include outputs, you must
commit the notebook's corresponding session JSON file, in the `__marimo__/session/`
@@ -115,6 +117,21 @@ directory that exists alongside the notebook. The session is automatically gener
you run the notebook from the marimo editor; you can also generate the session
from the command-line with `marimo export session notebook.py`
+#### WebAssembly previews
+
+To share a link to a live executable notebook hosted on GitHub, append `/wasm`
+to the URL or navigate to `Preview > WebAssembly`:
+
+<div align="center">
+ <img src="/_static/molab-wasm-preview.png" width="700px" alt="Screenshot of the molab Preview dropdown with options for Preview, Code, WebAssembly, and Server"/>
+</div>
+
+<p align="center"><em>Switch between static, WebAssembly, and server-backed previews from the Preview dropdown.</em></p>
+
+WebAssembly previews run [via Pyodide](wasm.md), so not all notebooks will
+work; however, like static previews, they don't require the viewer to login.
+They can also be embedded in iframes.
+
### Share open-in-molab badges
Share links to molab notebooks using our open in molab badge:
@@ -145,18 +162,16 @@ for a chance to be featured.
## Embed in other webpages
You can embed interactive molab notebooks in your own webpages using iframes.
-Obtain iframe snippets by clicking the share button on interactive [molab previews
-of GitHub notebooks](#mirror-notebooks-from-github), or construct
-embeddable URLs yourself using the recipes below.
+Obtain iframe snippets by clicking the share button on WebAssembly [molab previews
+of GitHub notebooks](#webassembly-previews):
-> Embedded notebooks run in the browser via WebAssembly, so your notebook must be
-[WebAssembly-compatible](wasm.md). We also recommend creating these notebooks
-[with `--sandbox`](package_management/inlining_dependencies.md) to make sure
-their dependencies get installed.
+<div align="center">
+ <img src="/_static/molab-copy-embed-iframe.png" width="618px" alt="Screenshot of the molab share dropdown on a WebAssembly preview, with a Copy Embed Iframe option"/>
+</div>
-### Embed notebooks from GitHub
+<p align="center"><em>Copy an embeddable iframe snippet from the share menu of a WebAssembly preview.</em></p>
-Add `?embed=true` to an [interactive preview URL](#interactive-previews) to get an embeddable notebook:
+This yields a snippet like the one below:
/// tab | Code
@@ -189,6 +204,12 @@ Add `?embed=true` to an [interactive preview URL](#interactive-previews) to get
///
+Embedded notebooks run in the browser via WebAssembly, so your notebook must be
+[WebAssembly-compatible](wasm.md). We also recommend creating these notebooks
+[with `--sandbox`](package_management/inlining_dependencies.md) to make sure
+their dependencies get installed.
+
+
### Embed from source code
You can embed a notebook directly from its source code, without hosting it on
diff --git a/docs/guides/publishing/github.md b/docs/guides/publishing/github.md
index a66a18afa6..38af4070c5 100644
--- a/docs/guides/publishing/github.md
+++ b/docs/guides/publishing/github.md
@@ -68,6 +68,27 @@ right corner:
<img src="/_static/docs-notebook-settings-snapshotting.jpg" alt="Notebook settings dialog showing the Exporting outputs section with HTML and ipynb checkboxes" style="max-width: 700px; width: 100%;" />
</picture>
+## Render live previews of notebooks with our browser extension
+
+Install the marimo glance browser extension for [Chrome](https://chromewebstore.google.com/detail/marimo-glance/emnkplkdlpojjembfbkdagibhmippjfg) or
+[Firefox](https://addons.mozilla.org/en-US/firefox/addon/marimo-glance/) to see
+live previews of notebooks on GitHub and GitLab. The extension detects marimo
+notebooks and adds a button to the bottom right of the page, that, with one
+click, replaces the raw Python file with an interactive notebook you can run,
+edit, and explore.
+
+marimo glance runs notebooks [with WebAssembly](../wasm.md), so not all notebooks will work.
+To run the notebook on a server, click "Open in molab" in the bottom
+left of the notebook.
+
+**Your code stays local.** The notebook source is packed into the page URL’s
+fragment and handed straight to the in-browser WebAssembly runtime. Browsers
+never send that fragment to any server, so your code — private repositories
+included — is never uploaded by the extension. The one exception is if you
+deliberately choose “Open in molab” from inside the notebook, which sends your
+code to molab to run and share there.
+
+
## Publish to GitHub Pages
> For a simpler solution, use [molab's built in GitHub previewer](../molab.md#mirror-notebooks-from-github)
diff --git a/docs/guides/working_with_data/dataframes.md b/docs/guides/working_with_data/dataframes.md
index 357fab0091..c4f9071125 100644
--- a/docs/guides/working_with_data/dataframes.md
+++ b/docs/guides/working_with_data/dataframes.md
@@ -11,7 +11,7 @@
_marimo integrates with [Pandas](https://pandas.pydata.org/) and
[Polars](https://pola.rs) dataframes natively_.
-For a video overview on interactive dataframes,
+For a video overview on interactive dataframes,
check out our [YouTube tutorial](https://www.youtube.com/watch?v=ZTs7vHzsqlQ).
## Displaying dataframes
@@ -147,7 +147,7 @@ notebook.
</figure>
</div>
-The transformations you apply will turn into code which is accessible via the "code" tab.
+The transformations you apply will turn into code which is accessible via the "code" tab.
<div align="center">
<figure>
@@ -198,7 +198,7 @@ transformed_df.value
///
-/// tab | live example
+/// tab | live example
/// marimo-embed
size: large
@@ -479,7 +479,7 @@ When you run a SQL cell in marimo, you can get the output returned as a datafram
</figure>
</div>
-Alternatively you can also use the [marimo configuration file](../configuration/index.md#user-configuration) to configure the default SQL output.
+Alternatively you can also use the [marimo configuration file](../configuration/index.md#user-settings) to configure the default SQL output.
```toml
[runtime]
diff --git a/mkdocs.yml b/mkdocs.yml
index 65831464ce..55d321833a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -367,6 +367,9 @@ repo_url: https://github.com/marimo-team/marimo
site_description: The next generation of Python notebooks
site_name: marimo
site_url: https://docs.marimo.io
+validation:
+ links:
+ anchors: warn
theme:
favicon: _static/favicon-32x32.png
features: