Skip to content

Commit 5025a89

Browse files
akshaykapre-commit-ci[bot]
akshayka
and
pre-commit-ci[bot]
authored
docs: WebAssembly Notebooks, Publishing to the Web (marimo-team#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>
1 parent ced11b6 commit 5025a89

15 files changed

+484
-244
lines changed

‎docs/guides/exporting.md

+10-45
Original file line numberDiff line numberDiff line change
@@ -149,8 +149,12 @@ Options:
149149

150150
!!! note "Note"
151151

152-
The exported file must be served over HTTP to function correctly - it cannot be opened directly from the filesystem (file://).
153-
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>.
152+
The exported file must be served over HTTP to function correctly - it
153+
cannot be opened directly from the filesystem (`file://`). Your server must
154+
also serve the assets in the `assets` directory, next to the HTML file. For
155+
a simpler publishing experience, publish to [GitHub
156+
Pages](publishing/github_pages.md) or use the [online
157+
playground](publishing/playground.md).
154158

155159
### Testing the export
156160

@@ -161,51 +165,12 @@ cd path/to/output_dir
161165
python -m http.server
162166
```
163167

164-
### Deploying to GitHub Pages
168+
### Publishing to GitHub Pages
165169

166-
/// admonition | Template repository
167-
type: tip
170+
After exporting your notebook to WASM HTML, you can publish it to
171+
[GitHub Pages](https://pages.github.com/) for free. See our [guide on
172+
GitHub Pages](publishing/github_pages.md) to learn more.
168173

169-
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.
170-
///
171-
172-
You can deploy your WebAssembly marimo notebook to GitHub Pages using the following GitHub Actions workflow:
173-
174-
```yaml
175-
jobs:
176-
build:
177-
runs-on: ubuntu-latest
178-
179-
steps:
180-
# ... checkout and install dependencies
181-
182-
- name: 📄 Export notebook
183-
run: |
184-
marimo export html-wasm notebook.py -o path/to/output --mode run
185-
186-
- name: 📦 Upload Pages Artifact
187-
uses: actions/upload-pages-artifact@v3
188-
with:
189-
path: path/to/output
190-
191-
deploy:
192-
needs: build
193-
runs-on: ubuntu-latest
194-
environment:
195-
name: github-pages
196-
url: ${{ steps.deployment.outputs.page_url }}
197-
198-
permissions:
199-
pages: write
200-
id-token: write
201-
202-
steps:
203-
- name: 🌐 Deploy to GitHub Pages
204-
id: deployment
205-
uses: actions/deploy-pages@v4
206-
with:
207-
artifact_name: github-pages
208-
```
209174

210175
### Exporting multiple notebooks
211176

‎docs/guides/index.md

+22-21
Original file line numberDiff line numberDiff line change
@@ -7,24 +7,25 @@ These guides cover marimo's core concepts.
77
Prefer a hands-on learning experience? marimo comes packaged with interactive
88
tutorials that you can launch with `marimo tutorial` at the command line.
99

10-
| Guide | Description |
11-
| :--------------------------------------------------- | :----------------------------------------------------------- |
12-
| [Reactive execution](reactivity.md) | Understanding how marimo runs cells |
13-
| [Interactive elements](interactivity.md) | Using interactive UI elements |
14-
| [Visualizing outputs](outputs.md) | Creating markdown, plots, and other visual outputs |
15-
| [Migrating from Jupyter](coming_from/jupyter.md) | Tips for transitioning from Jupyter |
16-
| [Expensive notebooks](expensive_notebooks.md) | Tips for working with expensive notebooks |
17-
| [Working with data](working_with_data/index.md) | Using SQL cells, no-code dataframe tools, and reactive plots |
18-
| [Apps](apps.md) | Running notebooks as apps |
19-
| [Scripts](scripts.md) | Running notebooks as scripts |
20-
| [Tests](testing/index.md) | Running unit tests in notebooks |
21-
| [Export to HTML and other formats](exporting.md) | Exporting notebooks to HTML and flat scripts |
22-
| [Run notebooks with WebAssembly](wasm.md) | Create notebooks in our online playground |
23-
| [Deploying](deploying/index.md) | Deploying marimo notebooks and apps |
24-
| [Editor Features](editor_features/index.md) | View variables, dataframe schemas, docstrings, and more |
25-
| [Configuration](configuration/index.md) | Configure various settings |
26-
| [Coming from other tools](coming_from/index.md) | Transitioning from Jupyter and other tools |
27-
| [Extending marimo](integrating_with_marimo/index.md) | Rich displays of objects, custom UI plugins |
28-
| [State management](state.md) | Advanced: mutable reactive state |
29-
| [Best practices](best_practices.md) | Best practices to help you get the most out of marimo |
30-
| [Troubleshooting](troubleshooting.md) | Troubleshooting notebooks |
10+
| Guide | Description |
11+
| :--------------------------------------------------- | :--------------------------------------------------------- |
12+
| [Running cells](reactivity.md) | Understanding how marimo runs cells |
13+
| [Interactive elements](interactivity.md) | Using interactive UI elements |
14+
| [Visualizing outputs](outputs.md) | Creating markdown, plots, and other visual outputs |
15+
| [Migrating from Jupyter](coming_from/jupyter.md) | Tips for transitioning from Jupyter |
16+
| [Expensive notebooks](expensive_notebooks.md) | Tips for working with expensive notebooks |
17+
| [Working with data](working_with_data/index.md) | Using SQL cells, no-code dataframe, and reactive plots |
18+
| [Apps](apps.md) | Running notebooks as apps |
19+
| [Scripts](scripts.md) | Running notebooks as scripts |
20+
| [Tests](testing/index.md) | Running unit tests in notebooks |
21+
| [Export notebooks](exporting.md) | Exporting notebooks to HTML, ipynb, flat scripts, and more |
22+
| [Publish to the web](publishing/index.md) | Edit and publish notebooks on the web |
23+
| [Run notebooks with WebAssembly](wasm.md) | Create notebooks in our online playground |
24+
| [Deploying](deploying/index.md) | Deploying marimo notebooks and apps |
25+
| [Editor Features](editor_features/index.md) | View variables, dataframe schemas, docstrings, and more |
26+
| [Configuration](configuration/index.md) | Configure various settings |
27+
| [Coming from other tools](coming_from/index.md) | Transitioning from Jupyter and other tools |
28+
| [Extending marimo](integrating_with_marimo/index.md) | Rich displays of objects, custom UI plugins |
29+
| [State management](state.md) | Advanced: mutable reactive state |
30+
| [Best practices](best_practices.md) | Best practices to help you get the most out of marimo |
31+
| [Troubleshooting](troubleshooting.md) | Troubleshooting notebooks |

‎docs/guides/interactivity.md

+8-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Interactive elements
22

33
One of marimo's most powerful features is its first-class support for
4-
interactive, stateful user interface (UI) elements, or "widgets": create them using
4+
interactive user interface (UI) elements, or "widgets", created using
55
[`marimo.ui`](../api/inputs/index.md). **Interacting with a UI element bound to a
66
global variable automatically runs all cells that reference it.**
77

@@ -11,9 +11,14 @@ global variable automatically runs all cells that reference it.**
1111
</figure>
1212
</div>
1313

14+
!!! example "Examples"
15+
See the [API reference](http://127.0.0.1:8000/api/inputs/) or our [GitHub
16+
repo](https://github.com/marimo-team/marimo/tree/main/examples/ui) for
17+
bite-sized examples on using input elements.
18+
1419
## How interactions run cells
1520

16-
Every UI element you make using `marimo.ui` has a value, accessible via its
21+
Every UI element you make using [`marimo.ui`](../api/inputs/index.md) has a value, accessible via its
1722
`value` attribute. When you interact with a UI element bound to a global
1823
variable, its value is sent back to Python. A single rule determines what
1924
happens next:
@@ -84,5 +89,5 @@ value on form submission.
8489
## Building custom UI elements using our plugin API
8590

8691
You can build your own reactive and interactive UI elements using
87-
[anywidget](https://github.com/manzt/anywidget)! See [our docs on
92+
[anywidget](https://github.com/manzt/anywidget). See [our docs on
8893
building custom UI elements](../guides/integrating_with_marimo/custom_ui_plugins.md) to learn more.

‎docs/guides/publishing/community_cloud/index.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Community Cloud
2+
3+
Our [Community Cloud](https://marimo.io/dashboard) is a free workspace
4+
for creating, saving, and sharing marimo notebooks. Unlike the
5+
[Playground](../playground.md), the Community Cloud requires a login. In
6+
return, it lets you save noteoboks, share them using email-based authorization,
7+
and upload a limited amount of data.
8+
9+
!!! note "WebAssembly notebooks only"
10+
11+
Currently, the Community Cloud only allows the creation of [WebAssembly
12+
notebooks](../../wasm.md). These are easy to share and embed in other
13+
web pages, but have some limitations in packages and performance.
14+
15+
Note: unlike our other publishing options, it is not possible to embed
16+
editable Community Cloud notebooks in other web pages.

‎docs/guides/publishing/deploy.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Deploy on backends
2+
3+
If you cannot use WebAssembly notebooks, you can deploy marimo notebooks via a
4+
traditional client-server model.
5+
6+
Both the edit server can be deployed as well as individual notebooks (as
7+
readonly apps).
8+
9+
Learn more in our [Deployment Guide](../deploying/index.md).

‎docs/guides/publishing/embedding.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Embedding
2+
3+
There are various ways to embed marimo notebooks in other web pages, such
4+
as web documentation, educational platforms, or static sites in general. Here
5+
are two ways:
6+
7+
* Host on [GitHub Pages](github_pages.md) or [self-host WASM HTML](self_host_wasm.md),
8+
and `<iframe>` the published notebook.
9+
* `<iframe>` a playground notebook, and [customize the embedding](playground.md#embedding-in-other-web-pages) with query params.
10+
(This is what we do throughout docs.marimo.io.)
11+
12+
We plan to provide more turn-key solutions for static site generation with
13+
marimo notebooks in the future.

‎docs/guides/publishing/github_pages.md

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Publish to GitHub Pages
2+
3+
You can publish executable notebooks to [GitHub Pages](https://pages.github.com/)
4+
for free, after exporting your notebook to a WebAssembly notebook.
5+
6+
## Export to WASM-powered HTML
7+
8+
Export your notebook to a self-contained HTML file that runs using [WebAssembly](../wasm.md):
9+
10+
/// tab | Export as a readonly app
11+
12+
```bash
13+
marimo export html-wasm notebook.py -o output_dir --mode run
14+
```
15+
16+
///
17+
18+
/// tab | Export as an editable notebook
19+
20+
```bash
21+
marimo export html-wasm notebook.py -o output_dir --mode edit
22+
```
23+
24+
///
25+
26+
See our [exporting guide](../exporting.md#export-to-wasm-powered-html) for
27+
the full documentation.
28+
29+
## Publish using GitHub Actions
30+
31+
/// tip | Template repository
32+
33+
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,
34+
for editable or readonly respectively.
35+
///
36+
37+
Publish to GitHub Pages using the following GitHub Actions workflow,
38+
which will republish your notebook on git push.
39+
40+
```yaml
41+
jobs:
42+
build:
43+
runs-on: ubuntu-latest
44+
45+
steps:
46+
# ... checkout and install dependencies
47+
48+
- name: 📄 Export notebook
49+
run: |
50+
marimo export html-wasm notebook.py -o path/to/output --mode run
51+
52+
- name: 📦 Upload Pages Artifact
53+
uses: actions/upload-pages-artifact@v3
54+
with:
55+
path: path/to/output
56+
57+
deploy:
58+
needs: build
59+
runs-on: ubuntu-latest
60+
environment:
61+
name: github-pages
62+
url: ${{ steps.deployment.outputs.page_url }}
63+
64+
permissions:
65+
pages: write
66+
id-token: write
67+
68+
steps:
69+
- name: 🌐 Deploy to GitHub Pages
70+
id: deployment
71+
uses: actions/deploy-pages@v4
72+
with:
73+
artifact_name: github-pages
74+
```
75+
76+
## Publish manually
77+
78+
You can also publish an exported notebook manually, through your repository
79+
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.

‎docs/guides/publishing/index.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Publishing notebooks to the web
2+
3+
You can publish marimo notebooks to the web as interactive editable notebooks,
4+
readonly web apps, or [static documents](../exporting.md).
5+
6+
Thanks to [WebAssembly](../wasm.md), you can even share executable
7+
notebooks on GitHub Pages or other static sites without paying for backend
8+
infrastrcture. This makes it easy to share your work with colleagues, embed
9+
executable notebooks in web documentation or educational websites, and more.
10+
11+
This guide provides an overview of the various ways to publish marimo notebooks.
12+
13+
| Guide | Description |
14+
| ----------------------------------------------------- | ------------------------------------------------------------ |
15+
| [Embedding](embedding.md) | An overview of embedding notebooks in other sites |
16+
| [GitHub Pages](github_pages.md) | Publishing interactive notebooks on GitHub Pages |
17+
| [Online playground](playground.md) | Sharing notebook links using our online playground |
18+
| [Community Cloud](community_cloud/index.md) | Save notebooks to our free Community Cloud |
19+
| [Self-host WebAssembly notebooks](self_host_wasm.md) | Self-hosting interactive WebAssembly (HTML export) notebooks |
20+
| [View notebooks on GitHub](view_outputs_on_github.md) | Viewing notebook outputs on GitHub |
21+
| [Deploy on a backend](deploy.md) | Deploying notebooks on backends |

0 commit comments

Comments
 (0)