docs: open playground notebooks from GitHub URL (#3399)

* Document how to open notebooks hosted on GitHub in the playground
* Document how this gets you access to the repo's entire file tree (!)
* Add a bookmarklet for convenience

docs/guides/exporting.md

@@ -165,6 +165,11 @@ cd path/to/output_dir
 python -m http.server
 ```
 
+### Including data files
+
+See the docs for [mo.notebook_location][marimo.notebook_location] to learn how
+to include data files in exported WASM HTML notebooks.
+
 ### Publishing to GitHub Pages
 
 After exporting your notebook to WASM HTML, you can publish it to

docs/guides/publishing/playground.md

@@ -4,7 +4,7 @@ Our [online playground](https://marimo.app) lets you
 create and share marimo notebooks for free, without creating an account.
 
 Playground notebooks are great for embedding in other web pages — all the
-notebooks embedding in marimo's own docs are playground notebooks. They
+embedded notebooks in marimo's own docs are playground notebooks. They
 are also great for sharing via links.
 
 **Try our playground!** Just navigate to
@@ -20,9 +20,9 @@ _The notebook embedded below is a playground notebook!_
 
 <iframe src="https://marimo.app/l/upciwv?embed=true" width="100%" height=400 frameBorder="0"></iframe>
 
-## Creating and sharing WASM notebooks
+## Creating and sharing playground notebooks
 
-WASM notebooks run at [marimo.app](https://marimo.app).
+Playground notebooks run at [marimo.app](https://marimo.app).
 
 ### New notebooks
 
@@ -48,9 +48,48 @@ notebook.
 
 Please be aware that marimo permalinks are publicly accessible.
 
-### Creating playground notebooks from GitHub
+### Open notebooks hosted on GitHub
 
-Use the "New > Open from URL" menu item to paste a link to a GitHub notebook.
+To open notebooks hosted on GitHub in the playground, just
+navigate to `https://marimo.app/path/to/notebook.py`. For example:
+<https://marimo.app/github.com/marimo-team/marimo/blob/main/examples/ui/slider.py>.
+
+!!! tip "Use our bookmarklet!"
+
+    For a convenient way to create notebooks from GitHub, drag and drop the
+    following button to your bookmarks bar:
+
+    <a href="javascript:(function(){let url=window.location.href.replace(/^https:\/\//,'');window.open('https://marimo.app/' + url, '_blank');})();" 
+          style="padding: 5px 10px; background-color: #007bff; color: white; text-decoration: none; border-radius: 5px; font-weight: bold;">
+    Open in marimo
+    </a>
+
+    Clicking the bookmark when you are viewing a notebook in GitHub will
+    open it in marimo.app.
+
+!!! note "From Jupyter notebooks"
+
+    You can also create Playground notebooks from Jupyter notebooks hosted
+    on GitHub. marimo will attempt to automatically convert the notebook
+    to a marimo notebook.
+
+#### Including data files
+
+Notebooks created from GitHub links have the entire contents of the repository
+mounted into the notebook's filesystem. This lets you work with files
+using regular Python file I/O!
+
+When constructing paths to data files, make sure to use
+[`mo.notebook_dir()`][marimo.notebook_dir] to ensure that paths work both
+locally and in the playground.
+
+!!! example "Example"
+
+    Navigate to
+
+    <https://marimo.app/github.com/marimo-team/marimo/blob/main/examples/misc/notebook_dir.py>
+
+    and open the file explorer panel to see all the files available to the notebook.
 
 ### Creating playground notebooks from local notebooks
 

docs/guides/wasm.md

@@ -125,9 +125,10 @@ hosted, you may need to use a CORS Proxy; see the [Pyodide
 documentation](https://pyodide.org/en/stable/usage/loading-packages.html#installing-wheels-from-arbitrary-urls)
 for more details.
 
-**Playground notebooks.** When opening [playground notebook](publishing/playground.md)
-from GitHub, the data files in the notebook directory are automatically
-downloaded and made available to your notebook.
+**Playground notebooks.** When opening a playground
+notebook from GitHub, all the files in the GitHub repo are made available to
+your notebook. See the [Playground
+Guide](publishing/playground.md#including-data-files) for more info.
 
 **Community Cloud notebooks.** Our free [Community
 Cloud](publishing/community_cloud/index.md) lets you upload a limited

examples/misc/notebook_dir.py

@@ -0,0 +1,23 @@
+import marimo
+
+__generated_with = "0.10.12"
+app = marimo.App(width="medium")
+
+
+@app.cell
+def _():
+    import marimo as mo
+    return (mo,)
+
+
+@app.cell
+def _(mo):
+    with open(mo.notebook_dir() / ".." / ".." / "pyproject.toml") as f:
+        contents = f.read()
+
+    mo.plain_text(contents)
+    return contents, f
+
+
+if __name__ == "__main__":
+    app.run()