| name | add-molab-badge |
| description | Add "Open in molab" badge(s) linking to marimo notebooks. Works with READMEs, docs, websites, or any markdown/HTML target. |
Add molab badge
Add "Open in molab" badge(s) linking to marimo notebooks. The badge can be added to any target: a GitHub README, documentation site, blog post, webpage, or any other markdown/HTML file.
Instructions
0. Session export for molab
molab previews render much nicer if the github repository has session information around. This can be added via:
uvx marimo export session notebook.py
uvx marimo export session folder/
This executes notebooks and exports their session snapshots, which molab uses to serve pre-rendered notebooks.
Key flags:
--sandbox — run each notebook in an isolated environment using PEP 723 dependencies--continue-on-error — keep processing other notebooks if one fails--force-overwrite — overwrite all existing snapshots, even if up-to-date
1. Determine the notebook links
The user may provide notebook links in one of two ways:
- User provides links directly. The user pastes URLs to notebooks. Use these as-is — no discovery needed.
- Notebook discovery (README target only). If the user asks you to add badges to a repository's README and doesn't specify which notebooks, discover them:
- Find all marimo notebook files (
.py files) in the repository. Use Glob with patterns like **/*.py and then check for the marimo header (import marimo or app = marimo.App) to confirm they are marimo notebooks.
- If the README already has links to notebooks (e.g., via
marimo.app links or existing badges), replace those.
- Otherwise, ask the user which notebooks should be linked.
2. Construct the molab URL
For each notebook, construct the molab URL using this format:
https://molab.marimo.io/github/{owner}/{repo}/blob/{branch}/{path_to_notebook}
{owner}/{repo}: the GitHub owner and repository name. Determine from the git remote (git remote get-url origin), the user-provided URL, or by asking the user.{branch}: typically main. Confirm from the repository's default branch.{path_to_notebook}: the path to the .py notebook file relative to the repository root.
3. Apply the /wasm suffix rules
- If replacing an existing
marimo.app link, append /wasm to the molab URL. This is because marimo.app runs notebooks client-side (WASM), so the molab equivalent needs the /wasm suffix to preserve that behavior.
- If adding a new badge (not replacing a
marimo.app link), do not append /wasm unless the user explicitly requests it.
4. Format the badge
Use the following markdown badge format:
[](URL)
Where URL is the constructed molab URL (with or without /wasm per the rules above).
For HTML targets, use:
<a href="URL"><img src="https://marimo.io/molab-shield.svg" alt="Open in molab" /></a>
5. Insert or replace badges in the target
- When replacing existing badges or links:
- Replace
marimo.app URLs with the equivalent molab.marimo.io URLs.
- Replace old shield image URLs (e.g.,
https://marimo.io/shield.svg or camo-proxied versions) with https://marimo.io/molab-shield.svg.
- Set the alt text to
Open in molab.
- Preserve surrounding text and structure.
- Edit the target file in place. Do not rewrite unrelated sections.
- If the user just wants the badge markdown/HTML (not editing a file), output it directly.
Examples
Replacing a marimo.app badge in a README:
Before:
[](https://marimo.app/github.com/owner/repo/blob/main/notebook.py)
After:
[](https://molab.marimo.io/github/owner/repo/blob/main/notebook.py/wasm)
Note: /wasm is appended because this replaces a marimo.app link.
Adding a new badge from user-provided links:
User says: "Add molab badges for these notebooks: https://github.com/owner/repo/blob/main/demo.py, https://github.com/owner/repo/blob/main/tutorial.py"
Output:
[](https://molab.marimo.io/github/owner/repo/blob/main/demo.py)
[](https://molab.marimo.io/github/owner/repo/blob/main/tutorial.py)
Note: no /wasm suffix by default for new badges.
