docs: WebAssembly Notebooks, Publishing to the Web (#3389)

Update the documentation to reflect various new developments with WebAssembly notebooks, and also add a new guide on publishing notebooks to the web. --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
marimo-team · Jan 9, 2025 · 5025a89 · 5025a89
1 parent ced11b6
commit 5025a89
Show file tree

Hide file tree

Showing 15 changed files with 484 additions and 244 deletions.
diff --git a/docs/guides/exporting.md b/docs/guides/exporting.md
@@ -149,8 +149,12 @@ Options:
 
 !!! note "Note"
 
-  The exported file must be served over HTTP to function correctly - it cannot be opened directly from the filesystem (file://).
-  Your server must also serve the assets in the `assets` directory, next to the HTML file. For this reason, we recommend using the online playground if possible: <https://marimo.app>.
+    The exported file must be served over HTTP to function correctly - it
+    cannot be opened directly from the filesystem (`file://`). Your server must
+    also serve the assets in the `assets` directory, next to the HTML file. For
+    a simpler publishing experience, publish to [GitHub
+    Pages](publishing/github_pages.md) or use the [online
+    playground](publishing/playground.md).
 
 ### Testing the export
 
@@ -161,51 +165,12 @@ cd path/to/output_dir
 python -m http.server
 ```
 
-### Deploying to GitHub Pages
+### Publishing to GitHub Pages
 
-/// admonition | Template repository
-    type: tip
+After exporting your notebook to WASM HTML, you can publish it to
+[GitHub Pages](https://pages.github.com/) for free. See our [guide on
+GitHub Pages](publishing/github_pages.md) to learn more.
 
-You can fork our [template repository](https://github.com/marimo-team/marimo-gh-pages-template) for deploying multiple notebooks to GitHub Pages. Once you have forked the repository, add your notebooks to the `notebooks`/`apps` directory.
-///
-
-You can deploy your WebAssembly marimo notebook to GitHub Pages using the following GitHub Actions workflow:
-
-```yaml
-jobs:
-  build:
-    runs-on: ubuntu-latest
-
-    steps:
-      # ... checkout and install dependencies
-
-      - name: 📄 Export notebook
-        run: |
-          marimo export html-wasm notebook.py -o path/to/output --mode run
-
-      - name: 📦 Upload Pages Artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: path/to/output
-
-  deploy:
-    needs: build
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-
-    permissions:
-      pages: write
-      id-token: write
-
-    steps:
-      - name: 🌐 Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
-        with:
-          artifact_name: github-pages
-```
 
 ### Exporting multiple notebooks
 

diff --git a/docs/guides/index.md b/docs/guides/index.md
@@ -7,24 +7,25 @@ These guides cover marimo's core concepts.
     Prefer a hands-on learning experience? marimo comes packaged with interactive
     tutorials that you can launch with `marimo tutorial` at the command line.
 
-| Guide                                                | Description                                                  |
-| :--------------------------------------------------- | :----------------------------------------------------------- |
-| [Reactive execution](reactivity.md)                  | Understanding how marimo runs cells                          |
-| [Interactive elements](interactivity.md)             | Using interactive UI elements                                |
-| [Visualizing outputs](outputs.md)                    | Creating markdown, plots, and other visual outputs           |
-| [Migrating from Jupyter](coming_from/jupyter.md)     | Tips for transitioning from Jupyter                          |
-| [Expensive notebooks](expensive_notebooks.md)        | Tips for working with expensive notebooks                    |
-| [Working with data](working_with_data/index.md)      | Using SQL cells, no-code dataframe tools, and reactive plots |
-| [Apps](apps.md)                                      | Running notebooks as apps                                    |
-| [Scripts](scripts.md)                                | Running notebooks as scripts                                 |
-| [Tests](testing/index.md)                            | Running unit tests in notebooks                              |
-| [Export to HTML and other formats](exporting.md)     | Exporting notebooks to HTML and flat scripts                 |
-| [Run notebooks with WebAssembly](wasm.md)            | Create notebooks in our online playground                    |
-| [Deploying](deploying/index.md)                      | Deploying marimo notebooks and apps                          |
-| [Editor Features](editor_features/index.md)          | View variables, dataframe schemas, docstrings, and more      |
-| [Configuration](configuration/index.md)              | Configure various settings                                   |
-| [Coming from other tools](coming_from/index.md)      | Transitioning from Jupyter and other tools                   |
-| [Extending marimo](integrating_with_marimo/index.md) | Rich displays of objects, custom UI plugins                  |
-| [State management](state.md)                         | Advanced: mutable reactive state                             |
-| [Best practices](best_practices.md)                  | Best practices to help you get the most out of marimo        |
-| [Troubleshooting](troubleshooting.md)                | Troubleshooting notebooks                                    |
+| Guide                                                | Description                                                |
+| :--------------------------------------------------- | :--------------------------------------------------------- |
+| [Running cells](reactivity.md)                       | Understanding how marimo runs cells                        |
+| [Interactive elements](interactivity.md)             | Using interactive UI elements                              |
+| [Visualizing outputs](outputs.md)                    | Creating markdown, plots, and other visual outputs         |
+| [Migrating from Jupyter](coming_from/jupyter.md)     | Tips for transitioning from Jupyter                        |
+| [Expensive notebooks](expensive_notebooks.md)        | Tips for working with expensive notebooks                  |
+| [Working with data](working_with_data/index.md)      | Using SQL cells, no-code dataframe, and reactive plots     |
+| [Apps](apps.md)                                      | Running notebooks as apps                                  |
+| [Scripts](scripts.md)                                | Running notebooks as scripts                               |
+| [Tests](testing/index.md)                            | Running unit tests in notebooks                            |
+| [Export notebooks](exporting.md)                     | Exporting notebooks to HTML, ipynb, flat scripts, and more |
+| [Publish to the web](publishing/index.md)             | Edit and publish notebooks on the web                      |
+| [Run notebooks with WebAssembly](wasm.md)            | Create notebooks in our online playground                  |
+| [Deploying](deploying/index.md)                      | Deploying marimo notebooks and apps                        |
+| [Editor Features](editor_features/index.md)          | View variables, dataframe schemas, docstrings, and more    |
+| [Configuration](configuration/index.md)              | Configure various settings                                 |
+| [Coming from other tools](coming_from/index.md)      | Transitioning from Jupyter and other tools                 |
+| [Extending marimo](integrating_with_marimo/index.md) | Rich displays of objects, custom UI plugins                |
+| [State management](state.md)                         | Advanced: mutable reactive state                           |
+| [Best practices](best_practices.md)                  | Best practices to help you get the most out of marimo      |
+| [Troubleshooting](troubleshooting.md)                | Troubleshooting notebooks                                  |
diff --git a/docs/guides/interactivity.md b/docs/guides/interactivity.md
@@ -1,7 +1,7 @@
 # Interactive elements
 
 One of marimo's most powerful features is its first-class support for
-interactive, stateful user interface (UI) elements, or "widgets": create them using
+interactive user interface (UI) elements, or "widgets", created using
 [`marimo.ui`](../api/inputs/index.md). **Interacting with a UI element bound to a
 global variable automatically runs all cells that reference it.**
 
@@ -11,9 +11,14 @@ global variable automatically runs all cells that reference it.**
 </figure>
 </div>
 
+!!! example "Examples"
+    See the [API reference](http://127.0.0.1:8000/api/inputs/) or our [GitHub
+    repo](https://github.com/marimo-team/marimo/tree/main/examples/ui) for
+    bite-sized examples on using input elements.
+
 ## How interactions run cells
 
-Every UI element you make using `marimo.ui` has a value, accessible via its
+Every UI element you make using [`marimo.ui`](../api/inputs/index.md) has a value, accessible via its
 `value` attribute. When you interact with a UI element bound to a global
 variable, its value is sent back to Python. A single rule determines what
 happens next:
@@ -84,5 +89,5 @@ value on form submission.
 ## Building custom UI elements using our plugin API
 
 You can build your own reactive and interactive UI elements using
-[anywidget](https://github.com/manzt/anywidget)! See [our docs on
+[anywidget](https://github.com/manzt/anywidget). See [our docs on
 building custom UI elements](../guides/integrating_with_marimo/custom_ui_plugins.md) to learn more.
diff --git a/docs/guides/publishing/community_cloud/index.md b/docs/guides/publishing/community_cloud/index.md
@@ -0,0 +1,16 @@
+# Community Cloud
+
+Our [Community Cloud](https://marimo.io/dashboard) is a free workspace
+for creating, saving, and sharing marimo notebooks. Unlike the
+[Playground](../playground.md), the Community Cloud requires a login. In
+return, it lets you save noteoboks, share them using email-based authorization,
+and upload a limited amount of data.
+
+!!! note "WebAssembly notebooks only"
+
+    Currently, the Community Cloud only allows the creation of [WebAssembly
+    notebooks](../../wasm.md). These are easy to share and embed in other
+    web pages, but have some limitations in packages and performance.
+
+Note: unlike our other publishing options, it is not possible to embed
+editable Community Cloud notebooks in other web pages.
diff --git a/docs/guides/publishing/deploy.md b/docs/guides/publishing/deploy.md
@@ -0,0 +1,9 @@
+# Deploy on backends
+
+If you cannot use WebAssembly notebooks, you can deploy marimo notebooks via a
+traditional client-server model.
+
+Both the edit server can be deployed as well as individual notebooks (as
+readonly apps).
+
+Learn more in our [Deployment Guide](../deploying/index.md).
diff --git a/docs/guides/publishing/embedding.md b/docs/guides/publishing/embedding.md
@@ -0,0 +1,13 @@
+# Embedding
+
+There are various ways to embed marimo notebooks in other web pages, such 
+as web documentation, educational platforms, or static sites in general. Here
+are two ways:
+
+* Host on [GitHub Pages](github_pages.md) or [self-host WASM HTML](self_host_wasm.md),
+  and `<iframe>` the published notebook.
+* `<iframe>` a playground notebook, and [customize the embedding](playground.md#embedding-in-other-web-pages) with query params.
+  (This is what we do throughout docs.marimo.io.)
+
+We plan to provide more turn-key solutions for static site generation with
+marimo notebooks in the future.
diff --git a/docs/guides/publishing/github_pages.md b/docs/guides/publishing/github_pages.md
@@ -0,0 +1,79 @@
+# Publish to GitHub Pages
+
+You can publish executable notebooks to [GitHub Pages](https://pages.github.com/)
+for free, after exporting your notebook to a WebAssembly notebook.
+
+## Export to WASM-powered HTML
+
+Export your notebook to a self-contained HTML file that runs using [WebAssembly](../wasm.md):
+
+/// tab | Export as a readonly app
+
+```bash
+marimo export html-wasm notebook.py -o output_dir --mode run
+```
+
+///
+
+/// tab | Export as an editable notebook
+
+```bash
+marimo export html-wasm notebook.py -o output_dir --mode edit
+```
+
+///
+
+See our [exporting guide](../exporting.md#export-to-wasm-powered-html) for
+the full documentation.
+
+## Publish using GitHub Actions
+
+/// tip | Template repository
+
+Fork our [template repository](https://github.com/marimo-team/marimo-gh-pages-template) for deploying multiple notebooks to GitHub Pages. Once you have forked the repository, add your notebooks to the `notebooks` or `apps` directories,
+for editable or readonly respectively.
+///
+
+Publish to GitHub Pages using the following GitHub Actions workflow,
+which will republish your notebook on git push.
+
+```yaml
+jobs:
+    build:
+        runs-on: ubuntu-latest
+
+        steps:
+            # ... checkout and install dependencies
+
+            - name: 📄 Export notebook
+              run: |
+                  marimo export html-wasm notebook.py -o path/to/output --mode run
+
+            - name: 📦 Upload Pages Artifact
+              uses: actions/upload-pages-artifact@v3
+              with:
+                  path: path/to/output
+
+    deploy:
+        needs: build
+        runs-on: ubuntu-latest
+        environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+
+        permissions:
+            pages: write
+            id-token: write
+
+        steps:
+            - name: 🌐 Deploy to GitHub Pages
+              id: deployment
+              uses: actions/deploy-pages@v4
+              with:
+                  artifact_name: github-pages
+```
+
+## Publish manually
+
+You can also publish an exported notebook manually, through your repository
+settings. Read [GitHub's documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) to learn more.
diff --git a/docs/guides/publishing/index.md b/docs/guides/publishing/index.md
@@ -0,0 +1,21 @@
+# Publishing notebooks to the web
+
+You can publish marimo notebooks to the web as interactive editable notebooks,
+readonly web apps, or [static documents](../exporting.md).
+
+Thanks to [WebAssembly](../wasm.md), you can even share executable
+notebooks on GitHub Pages or other static sites without paying for backend
+infrastrcture. This makes it easy to share your work with colleagues, embed
+executable notebooks in web documentation or educational websites, and more.
+
+This guide provides an overview of the various ways to publish marimo notebooks.
+
+| Guide                                                 | Description                                                  |
+| ----------------------------------------------------- | ------------------------------------------------------------ |
+| [Embedding](embedding.md)                             | An overview of embedding notebooks in other sites            |
+| [GitHub Pages](github_pages.md)                       | Publishing interactive notebooks on GitHub Pages             |
+| [Online playground](playground.md)                    | Sharing notebook links using our online playground           |
+| [Community Cloud](community_cloud/index.md)           | Save notebooks to our free Community Cloud                   |
+| [Self-host WebAssembly notebooks](self_host_wasm.md)  | Self-hosting interactive WebAssembly (HTML export) notebooks |
+| [View notebooks on GitHub](view_outputs_on_github.md) | Viewing notebook outputs on GitHub                           |
+| [Deploy on a backend](deploy.md)                      | Deploying notebooks on backends                              |