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: marimo glance (#10282)
Akshay Agrawal86f90f010326
diff --git a/docs/_static/docs-app-config.png b/docs/_static/docs-app-config.pngindex c19a597337..b74e93c1ab 100644Binary files a/docs/_static/docs-app-config.png and b/docs/_static/docs-app-config.png differdiff --git a/docs/_static/molab-copy-embed-iframe.png b/docs/_static/molab-copy-embed-iframe.pngnew file mode 100644index 0000000000..0b3e88569bBinary files /dev/null and b/docs/_static/molab-copy-embed-iframe.png differdiff --git a/docs/_static/molab-wasm-preview.png b/docs/_static/molab-wasm-preview.pngnew file mode 100644index 0000000000..425f798a9fBinary files /dev/null and b/docs/_static/molab-wasm-preview.png differdiff --git a/docs/faq.md b/docs/faq.mdindex 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 (sincethey're stored as `.py` files). In contrast, this requires extra steps todo 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'teasily 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.mdindex bcad395c85..0dd0702feb 100644--- a/docs/guides/coming_from/jupyter.md+++ b/docs/guides/coming_from/jupyter.md@@ -125,8 +125,8 @@ augmented_df = dfaugmented_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 namedcells 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, [enablethe "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 notebooksConvert 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 notebooksmarimo 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 notebooksExport to an `ipynb` file withdiff --git a/docs/guides/configuration/index.md b/docs/guides/configuration/index.mdindex 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 storedin 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 configurationYou 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 variablesmarimo supports the following environment variables for advanced configuration:diff --git a/docs/guides/molab.md b/docs/guides/molab.mdindex 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 mustcommit 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 generyou run the notebook from the marimo editor; you can also generate the sessionfrom 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 badgesShare links to molab notebooks using our open in molab badge:@@ -145,18 +162,16 @@ for a chance to be featured.## Embed in other webpagesYou 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 codeYou can embed a notebook directly from its source code, without hosting it ondiff --git a/docs/guides/publishing/github.md b/docs/guides/publishing/github.mdindex 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.mdindex 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-embedsize: 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.ymlindex 65831464ce..55d321833a 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -367,6 +367,9 @@ repo_url: https://github.com/marimo-team/marimosite_description: The next generation of Python notebookssite_name: marimosite_url: https://docs.marimo.io+validation:+ links:+ anchors: warntheme:favicon: _static/favicon-32x32.pngfeatures: