Skip to content

Update Colab badge URLs to support notebooks on gh-pages #359

@mmcky

Description

@mmcky

Background

As part of the QuantEcon Actions migration (see QuantEcon/actions#25 and PLAN.md), we're simplifying our notebook deployment architecture.

Current design:

  • Lecture repos (e.g., lecture-python.myst) build notebooks via sphinx-tojupyter
  • Notebooks are synced to separate .notebooks repos (e.g., lecture-python.notebooks)
  • Colab badges link to: https://colab.research.google.com/github/QuantEcon/{repo}.notebooks/blob/main/{path}

New design:

  • Notebooks are deployed to gh-pages alongside HTML content in _notebooks/ directory
  • Colab badges link to: https://colab.research.google.com/notebook?url=https://{domain}/_notebooks/{path}
  • Eliminates 4 separate .notebooks repos and sync workflows

Requested Changes

Update Colab badge/link generation to support notebooks hosted on gh-pages:

Current URL format:

https://colab.research.google.com/github/QuantEcon/lecture-python.notebooks/blob/main/example.ipynb

New URL format:

https://colab.research.google.com/notebook?url=https://python.quantecon.org/_notebooks/example.ipynb

Implementation Notes

  • Google Colab supports opening notebooks from any public URL via the url parameter
  • The {domain} should be configurable per lecture series:
    • lecture-python.mystpython.quantecon.org
    • lecture-python-programming.mystpython-programming.quantecon.org
    • lecture-python-intro → (Netlify domain)
    • lecture-python-advanced.mystpython-advanced.quantecon.org
  • Notebooks are already copied to _build/html/_notebooks/ via the build-lectures action with html-copy-notebooks: 'true'

Benefits

  • ✅ Reduces repo count from 8 to 4 (eliminates .notebooks repos)
  • ✅ Eliminates sync step in publish workflows
  • ✅ Single source of truth for notebooks
  • ✅ Simpler maintenance

Related

  • QuantEcon/actions PLAN.md — Migration strategy
  • QuantEcon/actions PR #25 — ML libs removal
  • Primary user access: (1) Download links on lecture pages, (2) Colab badges on lecture pages

Timeline

Needed for upcoming lecture repository migrations (Q1 2026).

cc @mmcky

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions