add-molab-badge

添加 molab 徽章

添加指向 marimo 笔记本的“在 molab 中打开”徽章。徽章可以添加到任意目标：GitHub README、文档网站、博客文章、网页或其他 Markdown/HTML 文件。

说明

0. 为 molab 导出会话

如果 GitHub 仓库包含会话信息，molab 的预览效果会更好。可以通过以下方式添加：

uvx marimo export session notebook.py
uvx marimo export session folder/

此命令会执行笔记本并导出其会话快照，molab 会使用这些快照提供预渲染的笔记本。

关键标志：

• --sandbox — 使用 PEP 723 依赖项，在隔离环境中运行每个笔记本
• --continue-on-error — 如果某个笔记本运行失败，继续处理其他笔记本
• --force-overwrite — 覆盖所有现有快照，即使它们已是最新版本

1. 确定笔记本链接

用户可以通过以下两种方式之一提供笔记本链接：

• 用户直接提供链接。 用户会粘贴笔记本 URL。直接使用这些链接，无需查找。
• 查找笔记本（仅限 README 目标）。 如果用户要求为仓库的 README 添加徽章，但未指定笔记本，请查找笔记本：
  1. 找出仓库中的所有 marimo 笔记本文件（.py 文件）。使用 Glob 和 **/*.py 等模式，然后检查是否包含 marimo 标头（import marimo 或 app = marimo.App），以确认这些文件是 marimo 笔记本。
  2. 如果 README 已包含笔记本链接（例如，通过 marimo.app 链接或现有徽章），请替换这些链接。
  3. 否则，询问用户希望链接到哪些笔记本。

2. 构造 molab URL

使用以下格式为每个笔记本构造 molab URL：

https://molab.marimo.io/github/{owner}/{repo}/blob/{branch}/{path_to_notebook}

• {owner}/{repo}：GitHub 所有者和仓库名称。通过 Git 远程地址（git remote get-url origin）、用户提供的 URL 确定，或询问用户。
• {branch}：通常为 main。请确认仓库的默认分支。
• {path_to_notebook}：相对于仓库根目录的 .py 笔记本文件路径。

3. 应用 /wasm 后缀规则

• 如果是替换现有的 marimo.app 链接，请在 molab URL 后添加 /wasm。这是因为 marimo.app 会在客户端运行笔记本（WASM），因此 molab 对应的链接需要使用 /wasm 后缀，以保持这一行为。
• 如果是添加新徽章（而非替换 marimo.app 链接），除非用户明确要求，否则不要添加 /wasm。

4. 设置徽章格式

使用以下 Markdown 徽章格式：

[![Open in molab](https://marimo.io/molab-shield.svg)](URL)

其中，URL 是构造出的 molab URL（根据上述规则，带或不带 /wasm）。

对于 HTML 目标，请使用：

<a href="URL"><img src="https://marimo.io/molab-shield.svg" alt="Open in molab" /></a>

5. 在目标中插入或替换徽章

• 替换现有徽章或链接时：
  • 将 marimo.app URL 替换为对应的 molab.marimo.io URL。
  • 将旧的盾牌图片 URL（例如 https://marimo.io/shield.svg 或经过 camo 代理的版本）替换为 https://marimo.io/molab-shield.svg。
  • 将替代文本设为 Open in molab。
  • 保留周围的文本和结构。
• 直接在目标文件中编辑。不要重写无关的章节。
• 如果用户只需要徽章的 Markdown/HTML（而不需要编辑文件），请直接输出。

示例

在 README 中替换 marimo.app 徽章：

之前：

[![](https://marimo.io/shield.svg)](https://marimo.app/github.com/owner/repo/blob/main/notebook.py)

之后：

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

注意：由于这里替换的是 marimo.app 链接，因此添加了 /wasm。

根据用户提供的链接添加新徽章：

用户说：“为以下笔记本添加 molab 徽章：https://github.com/owner/repo/blob/main/demo.py、https://github.com/owner/repo/blob/main/tutorial.py”

输出：

[![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)

注意：默认情况下，新徽章不添加 /wasm 后缀。