Lecture repos moving off the Sphinx theme have no checklist of what myst.yml and CI must now set #209

Part of #147 (parity study 2026-09-11 — migration readiness).

Revised in place 2026-09-11: the footer item follows the #203 decision (a theme default); two items came out of the #204 decision (the notebook header setting and the {raw} source rewrite); the launch item follows the #205 decision (explicit, opt-in launch options); and the #207 review added the site URL and old URLs items; and #210's close moved the Sphinx options with no counterpart into this page.

Problem

A lecture repo moving from quantecon-book-theme to this theme has to set up several things in myst.yml, in its lecture sources or in CI that its Sphinx build handled another way. Three came with the Sphinx theme and needed no per-repo setup: a hard-coded licence footer, a built-in MathJax macro set, and a per-page git lookup for "Last changed". The rest are set per repo today, but under _config.yml keys this theme does not read: the notebooks repo, the document language, the Google Analytics ID, and the description and keywords. The lecture sources also carry Sphinx-only {raw} blocks, and the notebook header now has to come from configuration. The docs explain most of the new mechanisms one feature at a time. No page lists them as steps for a migrating repo, and neither docs/ nor the README mentions maths macros at all.

mystmd's Jupyter Book config upgrade does not carry these settings across either. It reads the analytics ID only from the html section, sets project.github only from a top-level repository.url, and types sphinx.config as an opaque record that upgradeConfig never reads (config.ts:99-106, config.ts:147-236, config.ts:185-200). lecture-python-programming, for example, has no top-level repository key and keeps these settings under sphinx.config (_config.yml:17-69).

Item by item:

• Licence footer.
  • The book theme puts the CC BY-SA 4.0 badge, the licence sentence and "A theme by QuantEcon" on every page (layout.html:353-361).
  • Today this theme renders a footer only when site.parts.footer is set (PageContent.tsx:105), and the live lecture-wasm site shows no licence text (verified 2026-09-11).
  • Decided on Decide how the CC BY-SA licence footer survives the cutover: a theme default or a per-repo footer.md #203: the theme will render that notice and credit by default when a site sets no footer, and a site.parts.footer file replaces the whole default. A migrating repo adds nothing unless its content is under other terms.
• Maths macros.
  • When mathjax_path points at MathJax 3, the book theme adds a set of macros, including \epsilon → \varepsilon, \EE, \RR and \argmax (layout.html:14-50, __init__.py:631-635).
  • Here KaTeX renders the maths at build time. The only macros it gets are the math: entries from project or page frontmatter, plus a built-in \mbox (mdast.ts:341, math.ts:25-27, math.ts:214-227).
  • KaTeX maps \epsilon to the lunate ϵ (U+03F5) and \varepsilon to ε (U+03B5) (katex 0.16.33 in the theme's node_modules, dist/katex.js lines 4764 and 4784).
  • lecture-python-programming loads MathJax 3 with no mathjax3_config of its own (_config.yml:79), so it relies on the theme's macros. It uses \epsilon in python_by_example.md (example). The fa, fr, zh-cn and ml editions also set no mathjax3_config and use \epsilon in the same lecture (default branches, checked 2026-09-11).
  • Repos with their own mathjax3_config have macros to port as well. lecture-python.myst writes two of them in MathJax's [definition, nargs] array form (_config.yml:107-112). math: does not accept that form: each macro must be a string, or an object with a macro key (validators.ts:11-19). An array value is dropped with a "must be object, not array" validation error (checked 2026-09-11).
  • The Sphinx-built notebooks carry the macros too: lecture-python-advanced.notebooks' arma.ipynb opens with a markdown cell of \newcommand definitions. How macros reach notebooks exported by mystmd is not yet settled.
• "Last changed".
  • The book theme runs git itself for every page (__init__.py:665-684).
  • Here the git-metadata plugin has to be listed under project.plugins, and the build needs the full git history (docs/git-metadata.md:13-26).
  • lecture-python-programming's Sphinx CI and publish workflows already check out with fetch-depth: 0 (ci.yml:11-13, publish.yml:26-28). The experimental jb2 PR-preview workflow checks out without it (ci.yml:11).
• Notebook launch repo.
  • The book theme builds launch links only when nb_repository_url is set, and takes the notebook repo from that key rather than from repository_url (launch.py:40, launch.py:181-183, _config.yml:60-61).
  • This theme derives it from project.github: it drops a .myst suffix and appends .notebooks, unless launch_repo_url or launch_repo_suffix is set (LaunchButton.tsx:15-18, launchUrls.ts:30-43, docs/launch.md:8-23).
  • If the derived name is not a real notebooks repo, the Colab link is dead. lecture-wasm sets github to QuantEcon/lecture-wasm (myst.yml:16). Its live Colab link points at QuantEcon/lecture-wasm.notebooks, which returns HTTP 404 (verified 2026-09-11).
  • Decided on Launch control cannot be turned off and links to a nonexistent notebooks repo on sites without one #205: Launch becomes opt-in and explicit. It renders only when launch_notebook_repo is set and launch_colab is true, and no repository name is guessed. Three Sphinx sites whose nb_repository_url names a missing repository are fixed separately, in Drop nb_repository_url, which points at a notebooks repo that does not exist lecture-dp#60, Drop nb_repository_url, which points at a notebooks repo that does not exist lecture-python.zh-cn#279 and Drop nb_repository_url, which points at a notebooks repo that does not exist lecture-intro.zh-cn#305.
• Notebook header.
  • Sphinx wrote each lecture's {raw} jupyter logo header into its exported notebook. On mystmd the block shows as literal markup under the page title, and the fork's ipynb export drops it.
  • Decided on Notebook header {raw} blocks render as literal HTML source under lecture page titles #204: the header comes from a project setting, settings.myst_to_ipynb.header in myst.yml, which the ipynb export writes as each notebook's first cell (ipynb export has no project-level notebook header, so the QuantEcon logo is copied into 549 lecture source files as raw blocks mystmd#108, not yet shipped).
• {raw} blocks in the lecture sources.
  • 554 {raw} blocks across 18 lecture repos have no mystmd rendering: 549 notebook headers, 2 embedded iframes and 3 HTML tables (counted 2026-09-11).
  • Decided on Notebook header {raw} blocks render as literal HTML source under lecture page titles #204: a scripted rewrite runs before a repo's first mystmd build. It deletes the header blocks, turns the iframes into {iframe} and keeps the tables as HTML in the Markdown.
• Site URL.
  • Every lecture repository's Sphinx config sets html.baseurl (checked 2026-09-11), and Sphinx emits each page's canonical link from it.
  • This theme reads site.options.site_url for og:url, and for the canonical link once Pages emit no rel=canonical, and the favicon link 404s on sites served under a sub-path #207 ships. Without it neither is emitted. Neither lecture-wasm nor the jb2 branch sets it today.
• Old URLs.
  • Page URLs change at cutover: about_py.html becomes about-py/.
  • 17 repositories' Sphinx configs carry a rediraffe_redirects map, and four also carry sphinx-reredirects redirects.
  • mystmd writes no redirects yet. The site build cannot redirect old page URLs, so every link to a Sphinx lecture page breaks at the move to mystmd mystmd#113 proposes redirect pages for the old Sphinx paths and a site.redirects map.
• Document language.
  • Some editions set Sphinx language: fr in the fr edition (_config.yml:20) and zh_CN in lecture-python.zh-cn (_config.yml:37).
  • Some also set current_language and languages under html_theme_options (fr _config.yml:52, en _config.yml:38-51).
  • This theme reads only site.options.current_language, and without it the page is marked lang="en" (i18n.ts:187-191, root.tsx:247). The same value sets og:locale (seo.ts:107-108) and marks the current entry in the language switcher (docs/rtl-support.md:10-26).
• Analytics.
  • Lecture configs put the Google Analytics ID under html_theme_options.analytics.google_analytics_id (_config.yml:68-69). The study found an ID on 19 of the 21 lecture sites.
  • This theme reads site.options.analytics_google (template.yml:93-98, Document.tsx:147-150).
• Description and keywords.
  • Lecture configs set these at the top level and under html_theme_options (_config.yml:4, _config.yml:66-67). The study found both on all 21 lecture sites.
  • This theme reads them from page, project or site frontmatter ($.tsx:55-61, _index.tsx:45-47). docs/configuration.md does not list either key (configuration.md:47-54).
  • A comma-separated keywords string, as the Sphinx configs use, is split into a list (site/validators.ts:141-149, applied to project frontmatter at project/validators.ts:78).

The experimental jb2 conversion in QuantEcon/lecture-python-programming#363 (open) does not yet carry most of these. Its myst.yml sets project.github and a footer, but no plugins, math, description, keywords or site.options (myst.yml:16-18, myst.yml:90-96). Under #203 its footer.md is to be removed so the theme default applies.

Proposed change

Add a migration checklist page, docs/migrating.md, for lecture repos moving from quantecon-book-theme, and link it from the Pages table in docs/index.md:25-38. For each item, the page says what it replaces in the Sphinx build, what to do in the MyST build, and which page has the detail. This change is documentation only.

Sphinx options with no counterpart. The page also carries a single table of the book-theme options that have no counterpart in this theme, each with its reason: unused by the lecture sites, inert in the book theme, dropped by an earlier decision, or open in a named issue. docs/index.md points its promise ("where a Sphinx option has no counterpart, its page says so") at this table, and the docs review task on #147 makes that change. The keys, carried over from #210 (theme keys are in the book theme's theme.conf unless noted):

The maths recipe to include. Checked 2026-09-11 with the theme's KaTeX 0.16.33: \epsilon renders as U+03F5 by default and as U+03B5 with this macro.

project:
  math:
    '\epsilon': '\varepsilon'

Some items depend on work still open, so the page should describe the state as it stands when it lands:

• Launch item. Use the option names decided on Launch control cannot be turned off and links to a nonexistent notebooks repo on sites without one #205, and say that a site without a notebooks repository shows no Launch. Whether the theme also checks that each notebook exists before showing Launch is deferred on Launch control cannot be turned off and links to a nonexistent notebooks repo on sites without one #205, so describe what has shipped when the page lands.
• Notebook header item. Say whether ipynb export has no project-level notebook header, so the QuantEcon logo is copied into 549 lecture source files as raw blocks mystmd#108 has shipped.
• Lecture sources item. Say where the rewrite script lives, which is still open on Notebook header {raw} blocks render as literal HTML source under lecture page titles #204.
• Old URLs item. Say whether The site build cannot redirect old page URLs, so every link to a Sphinx lecture page breaks at the move to mystmd mystmd#113 has shipped.

Acceptance criteria

• docs/migrating.md covers all eleven items in the table above. Each item names the Sphinx setting or behaviour it replaces, what to do (a myst.yml entry, a file, a source rewrite or a workflow setting), and a link to the page with the detail.
• The maths item includes a project.math example that maps \epsilon to \varepsilon, says it applies to repos without their own mathjax3_config, and says MathJax's [definition, nargs] array-form macros must be rewritten as strings.
• The git-metadata item gives the plugin URL form from docs/git-metadata.md and requires fetch-depth: 0 on every workflow checkout that builds HTML.
• The launch item maps each Sphinx launch key to its Launch control cannot be turned off and links to a nonexistent notebooks repo on sites without one #205 option, says to set launch_notebook_repo only when that repository exists, and says that a site without one shows no Launch.
• The footer item says the theme renders the licence notice by default (Decide how the CC BY-SA licence footer survives the cutover: a theme default or a per-repo footer.md #203), and that a site.parts.footer file replaces the whole default.
• The notebook header item names settings.myst_to_ipynb.header, and says whether ipynb export has no project-level notebook header, so the QuantEcon logo is copied into 549 lecture source files as raw blocks mystmd#108 has shipped.
• The lecture sources item links the rewrite from Notebook header {raw} blocks render as literal HTML source under lecture page titles #204 and says it runs before a repo's first mystmd build.
• The site URL item maps html.baseurl to site.options.site_url, and says that canonical links and og:url need it.
• The old URLs item lists the repository's redirect maps, and says what The site build cannot redirect old page URLs, so every link to a Sphinx lecture page breaks at the move to mystmd mystmd#113 does with them or that it has not shipped.
• The page carries the no-counterpart table, and gives every key in it a reason.
• The page says these steps are manual: mystmd's Jupyter Book config upgrade does not read sphinx.config, where the lecture configs keep these settings.
• The docs/index.md Pages table links the new page.
• The "Other site keys the theme uses" table in docs/configuration.md lists project.description and project.keywords.
• The PR changes documentation only.

Context

• Source: the 2026-09-11 book-theme parity study, rows F015, F047, F084, F076, F081, F087 and F089 (report section 3.4, "Add to the migration checklist"). The study rates F087 and F089 as implemented; they appear here only as migration steps. The notebook header and {raw} source items came from the Notebook header {raw} blocks render as literal HTML source under lecture page titles #204 review decision (row X02).
• Evidence was re-checked at theme main d504555 (the v2.7.0 release commit); the study itself cited 5260864.
• Related: Book-theme parity cutover — tracking #147 (the cutover gate).
• Related: Retire the in-repo git-metadata plugin once the standalone release exists in quantecon-plugins.mystmd #157, retiring the in-repo git-metadata plugin once quantecon-plugins.mystmd has a standalone release. It will change the plugin URL this page gives.
• Related: [Experimental] Build the lectures with QuantEcon/mystmd instead of jupyter-book lecture-python-programming#363, the experimental jb2 conversion.
• Related: Decide how the CC BY-SA licence footer survives the cutover: a theme default or a per-repo footer.md #203 (licence-footer decision, F015), Notebook header {raw} blocks render as literal HTML source under lecture page titles #204 (notebook header and {raw} rewrite, X02), Launch control cannot be turned off and links to a nonexistent notebooks repo on sites without one #205 (the launch gap for sites with no notebooks repo, F073 and F076), and ipynb export has no project-level notebook header, so the QuantEcon logo is copied into 549 lecture source files as raw blocks mystmd#108 (the notebook header setting).
• Related: Pages emit no rel=canonical, and the favicon link 404s on sites served under a sub-path #207 (canonical links, which need site_url) and The site build cannot redirect old page URLs, so every link to a Sphinx lecture page breaks at the move to mystmd mystmd#113 (redirects for the old URLs).