shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 开发与工程API Key 暂未确认

Notebook to Webpage

将 ipynb 构建成可预览课程网页；链接默认新标签页打开，避开全屏按钮，适配 Gallery 每文件 URL。

person作者: VoyagerXhubOpenAPI
download下载资源包

Notebook → Webpage

以 ipynb 为内容来源构建静态 HTML，不执行训练、不自动补全练习、不改写源 Notebook。保持图片、文字、代码和已有输出的含义。网页构建与 Gallery 发布分开；需要 GitHub 自动同步时配合 $github-to-gallery。

新用户与项目识别

先阅读 Gallery、账号与 token 入门。向不熟悉魔搭的用户简要解释 Gallery 是保留目录结构的多文件发布/预览空间，以及网页预览与 Notebook 运行的区别。复用会话已有信息，不要求用户懂平台术语。

先列出源 Notebook、图片、Python 模块、数据和现有 HTML；识别真实默认分支、课程阅读顺序及相对路径。不要假定目录名为 tutorials/course_content，不要假定存在 index.ipynb，不要把任何示例作者和 Gallery 当成默认目标。

构建步骤

  1. 检查 Notebook 目录、图片/辅助文件、现有构建脚本和许可证；有 Gallery 时读取真实 Gallery URL 与可选 GitHub URL；还没有 Gallery 时可省略 gallery_url，先构建本地预览，不需要账号或 token。优先修改已有构建逻辑。
  2. 复制本 Skill 的 scripts/build_html.py 为项目根目录 build_html.py；复制整个 assets/ 为根目录 notebook_web_assets/。这包含本地 MathJax 3.2.2、许可证、归属说明、样式和脚本，保留第三方归属。
  3. 按 页面配置与规则 写 notebook-web.json。安装构建环境缺少的 nbformat、nbconvert、beautifulsoup4、Pygments；镜像已安装则不要给课程 Notebook 添加重复 %pip install。
  4. 运行 python build_html.py。脚本不执行 Notebook；源文件按相对目录生成 HTML，因此同名不同目录的 Notebook 不冲突。自动生成输出根 index.html 课程导航，若源根目录 index.ipynb 存在则使用其内容。支持多层目录、同名文件、空格/中文路径和大小写后缀；用 notebook_order 显式指定阅读顺序，exclude_notebooks 排除草稿。
  5. 从项目根目录启动 python -m http.server 8000，预览实际 output_dir 下的 index.html（例如 /site/index.html），检查桌面和窄屏、侧栏、目录、公式和图片。不要把 nbconvert 成功等同于视觉验收成功。
  6. 发布时选 Gallery website 类型，EntryFile 设为 course_content/html/index.html 等相对路径。把整个输出目录（含 _static）纳入发布，检查文件预算与大小。需要更新现有 Gallery 时使用另一个 Skill；本构建脚本不会上传。

移动端适配（必须）

必须使用真实 viewport 和 touch emulation 检查手机、平板及桌面；不要把 aria-expanded 变化、media query 存在或 nbconvert 成功当作适配完成。按 移动布局与浏览器验收 实施并验收：

  • 1024px 及以下默认收起目录，使用抽屉、遮罩、关闭按钮，支持点外部、导航后和 Escape 关闭；关闭时不可见、不可点、不可键盘聚焦。菜单、链接和复制按钮触控区域至少 44px。手机将 Notebook/GitHub 操作放进抽屉，顶栏保留品牌、菜单与全屏控件空间。
  • 正文、长链接、图片和所有父容器适应 viewport；不要用 body 的 overflow-x:hidden 掩盖溢出。代码保留格式，在单一 pre 容器中局部横向滚动，支持原生触摸滑动；默认不增加额外滑条、百分比或提示文字；输出、表格与公式同样处理局部宽内容。
  • 运行随附 scripts/check_mobile.py 检查生成目录；它覆盖 320/375/390/768/820/1024/1280px、独立页面与 iframe，并实际验证抽屉可见性、原生横向滚动和触摸滚动改变代码 scrollLeft。代码不存在时如实报告该项未覆盖。检查截图，并在用户提供的平台环境复核嵌入与全屏效果。
  • 区分内容与平台能力：2026-10-23 用户反馈生产 Gallery 尚不支持移动端预览，预发刚支持；这是当时的平台状态，后续需重新核实。使用用户提供的实际预发/正式环境地址验收，不擅自构造预发地址、不把生产 token 发往预发。不因独立页面或模拟 iframe 通过就声称真实 Gallery 移动端已通过；环境不可访问时报告具体错误及未验收范围。
  • CSS/JS 静态资源 URL 使用内容哈希版本，防止 Gallery 中缓存旧布局。桌面链接继续默认新标签打开。

必须保留的产品规则

  • 链接默认在新标签页打开：Notebook 按钮、GitHub、正文跨页链接、课程导航等设置 target="_blank" rel="noopener noreferrer"。本页目录的 #anchor 保留页内跳转，避免开新标签破坏定位。
  • 右上角有 Gallery 全屏按钮：顶栏按钮组整体向左留出至少额外 48 px（加上原有页面 padding），不要把 GitHub 放在最右边。脚本 fullscreen_clearance_px 可加大；分别检查嵌入与全屏、桌面与移动端，不能只看独立 HTML。
  • Gallery 已支持每文件稳定 URL：https://modelscope.cn/gallery/{owner}/{gallery-path}/files/{relative-path}，支持目录结构。把“源 Notebook”与“魔搭运行”合并成“查看和运行 Notebook”，指向本页对应 ipynb 的 URL；不要所有页都指向 Gallery 首页或 index.ipynb。未配置 Gallery URL 的本地预览显示“查看 Notebook 源文件”，不暗示可在线运行；接入真实 Gallery URL 后重新构建。
  • 例如 .../files/chapters/02/lesson.ipynb。URL 逐段编码，保留 /。此路由是文件页面，不是原始文件直链。不要硬编码有有效期的 OSS 下载签名 URL。
  • 只在 HTML 中隐藏用户指定的说明或初始化 cell。优先使用 hide-web 或 remove_cell 标签；也可用配置中的源文本标记过滤。保留 ipynb 的 cell、输出和元数据。不要按“前两个 cell”一刀切，也不要自动删除来源/许可证信息。
  • 用户要求隐藏适配来源说明时，仍通过页面页脚或可访问的归属文件保留必要的版权与素材归属。正文和 Notebook 原始许可证要求继续适用。

资源与验收

脚本将本地图片内嵌为 data URL，使用本地 MathJax；不依赖在线 CDN。远程图片仍按原地址引用，不承诺自动离线化，应明确列出并按授权搬运。不要执行不可信 Notebook 或假定导出 HTML 已安全清洗；公开发布前检查富输出里的脚本和 iframe。

核对每页对应 Notebook URL、新标签属性、全屏预留空间、所有静态资源与图片可用、Notebook 源字节未修改、被隐藏 cell 不出现在网页。导航输出文件未入 Git 时，发布脚本也必须包含生成目录。移除已删除 Notebook 时先检查并清理旧生成页面；构建脚本不会递归删除用户目录。