Launch control cannot be turned off and links to a nonexistent notebooks repo on sites without one #205

Part of #147 (parity study 2026-09-11 — content correctness).

Revised in place 2026-09-11 after the maintainer review:

• Decided: the Launch control becomes opt-in and explicitly configured, with option names designed for more launch services.
• Deferred: whether and where the theme checks that a notebook exists before showing Launch. The options are documented below.

The revision is recorded in the comments.

Problem

The Launch control (in the desktop toolbar and the mobile overflow menu) appears on every page of any project that sets project.github. It opens Colab on a notebook repository whose name the theme guesses: the source repository, minus any .myst suffix, plus .notebooks. Only launch_repo_url or launch_repo_suffix override the guess, and no option hides the control. A site without a notebooks repository therefore links readers to Colab on a repository that does not exist. For example, lecture-wasm's /cobweb/ opens https://colab.research.google.com/github/QuantEcon/lecture-wasm.notebooks/blob/main/cobweb.ipynb, and that repository returns 404 (verified 2026-09-11).

The book theme never guesses. It shows Launch only when nb_repository_url is set (layout.html L418-L420, launch.py L40), and adds each service only when that service is configured: Colab needs launch_buttons.colab_url (launch.py L124-L129).

Where this theme does it:

• The notebook repository comes from project.github, and the only early return is a missing repo or page location (LaunchButton.tsx L15-L31).
• The name is always derived as source plus suffix, unless launch_repo_url is set (launchUrls.ts L30-L43).
• Five launch_* string options change the URL, and none turns the control off (template.yml L106-L123).

What the lecture repositories have (verified 2026-09-11)

The last row is fixed on the Sphinx side by QuantEcon/lecture-dp#60, QuantEcon/lecture-python.zh-cn#279 and QuantEcon/lecture-intro.zh-cn#305. Each removes the dead nb_repository_url, following QuantEcon/lecture-python-programming.fa#145.

Decision (2026-09-11)

1. Opt-in and explicit. Launch renders only when a notebook source is configured and at least one launch service is enabled. The theme stops guessing: the derivation from project.github, the .myst rule and launch_repo_suffix all go.

2. Flat option names now, shaped for nesting later. Theme options can only be boolean, string, number, choice or file, in both the QuantEcon mystmd fork and upstream, so a nested block cannot be declared yet. Template options can only be scalars, so site templates pack lists and nested settings into YAML strings mystmd#112 asks for structured options. Each flat name is the future nested path with underscores, so the migration is mechanical:

   Option (flat, now)	Nested, once mystmd supports it	Replaces	Sphinx equivalent
   launch_notebook_repo	launch.notebook.repo	launch_repo_url	nb_repository_url
   launch_notebook_branch (default main)	launch.notebook.branch	launch_branch	nb_branch
   launch_notebook_dir	launch.notebook.dir	launch_notebooks_path	nb_path_to_notebooks
   launch_notebook_source_dir	launch.notebook.source_dir	launch_source_path	path_to_docs
   launch_colab	launch.colab	(implicit today)	launch_buttons.colab_url
   launch_notebook_url (future)	launch.notebook.url	—	Update Colab badge URLs to support notebooks on gh-pages quantecon-book-theme#359 (notebooks served from the site)
   launch_binderhub_url, launch_jupyterhub_url (future)	launch.binderhub_url, launch.jupyterhub_url	—	launch_buttons.binderhub_url, launch_buttons.jupyterhub_url

   launch_repo_suffix is removed. All names are snake_case, like every other theme option.

3. Launch services are kept apart from the notebook source. The launch_notebook_* group says where the notebook lives; launch_colab and the future service keys say what can open it. One source serves every service, so a service is not a property of the notebook. With more than one service enabled, the control becomes a menu, and that needs no config change.

4. Migration. A lecture repository sets launch_notebook_repo only if that repository exists; the step is on the migration checklist (Lecture repos moving off the Sphinx theme have no checklist of what myst.yml and CI must now set #209).

   • lecture-wasm loses its dead link at its next theme bump, with no config change.
   • lecture-python-programming's jb2 branch adds launch_notebook_repo and launch_colab: true to keep its Colab link.

Deferred: checking the notebook exists before Launch is shown

The maintainer wants a failsafe, so that Launch never opens a missing notebook. Where that check runs is not decided yet. Current thinking: an in-page script that shows Launch only when it finds the referenced notebook.

Whichever approach is chosen:

• Fail closed: hide the control on a timeout or error.
• Keep the toolbar steady: no layout shift and no empty slot (the toolbar's optional slots use empty:hidden).
• Decide per page.
• Test the hidden state.

Acceptance criteria

• Launch (desktop toolbar and mobile overflow menu) renders only when launch_notebook_repo is set and launch_colab is true. With either unset, there is no Launch control and no empty toolbar slot.
• The Colab URL is built from launch_notebook_repo, launch_notebook_branch, launch_notebook_dir and launch_notebook_source_dir, and nothing is derived from project.github. launch_repo_suffix and the .myst rule are gone.
• The options are declared in template.yml and listed in docs/configuration.md.
• docs/launch.md and the README explain the options, map them from the Sphinx keys, and say that a site without a notebook source shows no Launch.
• tests/unit/launch-urls.test.mjs covers the new options. The visual fixture sets launch_notebook_repo and launch_colab for the launch-colab test, and a new test asserts that no Launch control renders without them.
• The CHANGELOG records the opt-in default and the renamed and removed options, as a breaking change for sites that relied on the guessed repository.
• The deferred existence check is either implemented as decided above, or split into its own issue before this one closes.
• After the release, live lecture-wasm shows no Launch link, and the jb2 build keeps its Colab link with the two new options.

Context

• Source: the 2026-09-11 book-theme parity study, rows F073 (Google Colab launch link) and F076 (notebook repository mapping).
• Why not hide_launch: the first version of this issue proposed an opt-out option beside hide_toc and hide_search. The hide_toc and hide_search options are declared and documented but have no effect #213 shows those two options have no effect, and opt-out keeps dead links as the default.
• Related, launch services: Feature: Add BinderHub support to Launch Notebook #26 (BinderHub), Feature: JupyterHub launch support — config-driven links (replacing the option removed in #87) #153 (JupyterHub links) and Feature: connect in-page compute to a running Jupyter server (Thebe server: backend, incl. localhost) #154 (Thebe server). All of them need a notebook source, which the options above provide.
• Related, config and checklist: Template options can only be scalars, so site templates pack lists and nested settings into YAML strings mystmd#112 (structured template options) and Lecture repos moving off the Sphinx theme have no checklist of what myst.yml and CI must now set #209 (migration checklist).
• Related, notebook hosting: QuantEcon/workspace-lectures#12 (notebook sync, which records that lecture-dp has no notebooks repository) and Update Colab badge URLs to support notebooks on gh-pages quantecon-book-theme#359 (notebooks served from the site).
• Overlap: open PR feat(compute): per-lecture live compute via an enable_live_compute site option #195 also edits template.yml, app/types.ts, the docs and theme.spec.ts, so whichever lands second rebases.
• Out of scope (F076, latent, no lecture site affected): a sub-path inside a repository URL, and non-GitHub repository URLs, which the book theme warns about and skips (launch.py L51-L53).