QuantEcon / QuantEcon/quantecon-book-theme

Update Colab badge URLs to support notebooks on gh-pages

Open
#359 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Jupyter Notebook
Stars
56
Forks
24
Avg merge
4h 33m
Merged PRs (30d)
4

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read PLAN.md and review the build-lectures configuration that copies notebooks into _build/html/_notebooks/. Trace the existing Colab badge generation and its current GitHub URL format. Done means configurable lecture domains produce the new notebook?url links for notebooks hosted under _notebooks/.

Written by the indexing model from the issue text.

Assessment

Tech stack
jupyter-notebook
Domain
documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.