add-molab-badge

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:
  1. 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.
  2. If the README already has links to notebooks (e.g., via marimo.app links or existing badges), replace those.
  3. 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:

[![Open in molab](https://marimo.io/molab-shield.svg)](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.io/shield.svg)](https://marimo.app/github.com/owner/repo/blob/main/notebook.py)

After:

[![Open in molab](https://marimo.io/molab-shield.svg)](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:

[![Open in molab](https://marimo.io/molab-shield.svg)](https://molab.marimo.io/github/owner/repo/blob/main/demo.py)
[![Open in molab](https://marimo.io/molab-shield.svg)](https://molab.marimo.io/github/owner/repo/blob/main/tutorial.py)

Note: no /wasm suffix by default for new badges.**