Repository navigation
Book-theme parity cutover — tracking #147
Description
Repository: QuantEcon/quantecon-theme.mystmd
Revised: 2026-09-14 (nineteenth revision, final) — main @ 2ca0288 (v3.0.0); latest release v3.0.0 (2026-09-12); open PRs #195 (#114) off the gate; gate complete: every sub-issue is closed, v3.0.0 carries the work, and both consumers have taken it. #183 and #181 moved back to the design review #187
Scope: everything that must land before the all-at-once migration of the QuantEcon lecture series to MyST / Jupyter Book ≥2 on this theme.
Sources: PLAN.md on main; the book-theme parity milestone; the #93 maintainer resolutions (2026-08-24, recorded in #145); the 2026-09-04 scope change on #143; the 2026-09-11 parity validation study (quantecon-book-theme @ 649cc376, this theme @ 5260864, 103 features assessed and adversarially verified, headline claims re-checked against live sites).
This is a long-lived tracker, not a period plan: it is the single source of truth for cutover-gate state, revised in place against live state rather than accumulating narrative, and it is resumed and updated but never session-closed. Revision history is in the comments.
Outcome — gate complete
Every gate item is closed, released and in consumers' hands. The validation study's gaps were implemented one issue per PR on 2026-09-12 and released together in v3.0.0 (2026-09-12), a major release because #205 makes Launch opt-in. Both consumers moved to it the same day: QuantEcon/lecture-wasm#78 is merged on main, and QuantEcon/lecture-python-programming#629 is merged into jb2, the branch behind the experimental build PR QuantEcon/lecture-python-programming#363.
#183 and #181 moved back to #187 on 2026-09-14, by maintainer decision: both are style questions for @DrDrij's design review, not parity defects the cutover waits on. That leaves this issue with no open sub-issues, and the book-theme parity milestone at 0 open and 21 closed.
What still gates the cutover is outside this theme: QuantEcon/mystmd#113 (redirects for the old Sphinx URLs) blocks it, and the source rewrite is coordinated in QuantEcon/workspace-lectures#64. Both are under Sequencing.
| Item | Decision | Landed |
|---|---|---|
| #203 licence footer | decision: a theme default, with a site's footer.md replacing it whole |
✅ #221, v3.0.0 |
#204 notebook header {raw} blocks |
revision: the sources become mystmd-native through a rewrite script, and the header moves to a project setting (QuantEcon/mystmd#108) | ✅ #222 (scripts/rewrite-raw-blocks.mjs, run by the PR preview), v3.0.0 |
| #205 Launch control | decision: opt-in and explicit, through flat launch_* options, and no repository name is guessed |
✅ #224, v3.0.0 (breaking). The notebook-existence check is deferred to #223 |
| #206 output plot alignment | decision: images in cell outputs are centred, while tables and text stay left-aligned | ✅ #225, v3.0.0 |
| #207 canonical link and favicon | decision: canonical and og:url come from site_url, and every head link is aware of the base URL |
✅ #227, v3.0.0 |
| #208 outline h4 entries | decision: h2 to h4 in a tree of any depth, expanding as the Sphinx panel does | ✅ #228, v3.0.0 |
| #209 migration checklist | revision: a checklist page, with the no-counterpart table | ✅ #226 (docs/migrating.md), v3.0.0 |
| #210 parity record | closed and split into #217 and #218 | ➖ not planned |
| #217 docs review | Review README, docs/ and CONTRIBUTING.md against what shipped |
✅ #229, plus the README's pinned v3.0.0 URLs in #236 |
| #218 PLAN.md close-out | Move the lasting guidance to CONTRIBUTING.md and add a closing note to PLAN.md | ✅ #230 |
| #183, #181 | Style questions that wait on @DrDrij (#183, #181) | ↩️ moved back to #187 on 2026-09-14 |
Spun out of the review:
- Notebook header: 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 header setting for the ipynb export.
- Export gaps: ipynb export writes tables with colspan or rowspan as pipe tables, which cannot express merged cells, so the columns misalign mystmd#109 (span tables), ipynb export with markdown: commonmark writes {iframe} as MyST directive syntax, which Jupyter and Colab show as a literal code block mystmd#110 (
{iframe}undermarkdown: commonmark) and ipynb export drops every raw node, including {raw} text and {raw} latex content, and logs an error that --strict does not count mystmd#111 (rawnodes). - Source migration: QuantEcon/workspace-lectures#64, the jb1 → jb2 source-migration project. It inventories every construct mystmd does not render across 20 lecture repos, and plans the cutover rewrite as one PR per repo; its tooling is QuantEcon/workspace-lectures#65 (open).
- New constructs: that inventory found four no issue had covered: capitalised
{prf:Theorem},{any},{todo}and{fas}. - Structured theme options: Template options can only be scalars, so site templates pack lists and nested settings into YAML strings mystmd#112 asks mystmd for object and list template options, so the flat launch options, and
languagesandtranslators, can become nested settings. - Dead Colab links on the Sphinx sites: 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 (all still open) remove
nb_repository_urlvalues that name missing notebooks repositories. - DataFrame outputs: HTML notebook outputs such as pandas DataFrames are missing from the served page and appear only after JavaScript runs #216. HTML outputs such as pandas DataFrames are missing from the served page and render only after JavaScript runs.
- Old URLs at cutover: The site build cannot redirect old page URLs, so every link to a Sphinx lecture page breaks at the move to mystmd mystmd#113.
- From PLAN.md and the user docs claim book-theme parity and behaviour that the code does not deliver #210's close: The open contents drawer covers the start of the lecture text between 1024px and 1339px wide #219 (the open contents drawer covers text at 1024–1339px), The font-size setting resets on every page load and is not offered on mobile #220 (the font size resets on every load and is not offered on mobile), and the dark-palette question, now Which dark palette this theme ships: the pre-0.18.0 greys it has, the book theme's navy-charcoal, or its own #237 under Design review of the v2.5.0 lecture build #187.
- From implementation: Decide whether the theme checks a notebook exists before showing Launch #223 (whether to check that a notebook exists before showing Launch), plus the tooling issues npm run format is unconfigured and would rewrite 62 of 64 files against the repo's own style #231–Two serve.sh instances on the same fixture race by rewriting myst.yml #234.
Background
The parity project brings this theme to feature parity with quantecon-book-theme (Sphinx, JB<2) ahead of migrating the lecture series. Phases 0–2 (release infrastructure, git-history headers, launch parity with Colab + in-page JupyterLite/Thebe) shipped in v2.3.0 (2026-08-20); lecture-wasm is live on it and has tracked every release since (v2.7.0 as of QuantEcon/lecture-wasm#77, 2026-09-11). The #93 maintainer decisions (closed 2026-08-24) settled the remaining strategy: features are built local-first with upstreaming deferred to a registry (UPSTREAM-CANDIDATES.yml), and — most consequentially — the migration is all-or-nothing: every lecture series moves at once, onto a single common publishing base, when parity is complete. That decision converts the remaining parity backlog from nice-to-have into a hard cutover gate, and this issue is the single tracker for that gate.
One #93 resolution has since been superseded: the git-metadata plugin was to live permanently in this repo, but decision D8 of the report-theme design review (2026-09-02) created QuantEcon/quantecon-plugins.mystmd as the plugin family's home. The move is QuantEcon/quantecon-plugins.mystmd#11, this repo's side of it is #157, and the living-document corrections are #159. It does not gate the cutover.
Where we stand (verified 2026-09-14)
The gate is complete. Phases 0–6 were released by v2.7.0, and the gaps found by the 2026-09-11 validation study by v3.0.0.
| Area | State |
|---|---|
| Phases 0–2 (release infra, git history, launch/live compute) | ✅ shipped v2.3.0 |
| Live compute correctness on shipped surface (#117) | ✅ fixed (#137), released in v2.3.1 |
| Static builds of the self-hosted stylesheets (#138) | ✅ fixed (#139), released in v2.3.1 |
| Residual static-build defect in route stylesheets (#150) | ✅ fixed (#151), released in v2.4.0 |
| Private JupyterHub launch option (#87) | ✅ removed (#152), released in v2.5.0 |
| Phase 3 — code highlighting + colour schemes (#89) | ✅ merged (#171), released in v2.6.0 — defaults only, switches deferred; contrast decision open in #172 |
| Phases 4+5 — i18n + RTL (#90, #91) | ✅ merged (#174), released in v2.6.0 — no translated edition builds on it yet |
| Translator attribution (#143) | ✅ merged (#174), released in v2.6.0, on the book-theme v0.22.0 placement |
| Back navigation on static builds (#186) | ✅ merged (#192), released in v2.6.1 |
| Pinned, scroll-tracking "On this page" outline (#182) | ✅ merged (#196), released in v2.7.0 |
| Phase 6 — Meta/SEO + collapsible stderr + parity docs (#92) | ✅ merged (#197), released in v2.7.0 |
| Parity validation study gaps (#203–#209, #217, #218) | ✅ merged (#221, #222, #224–#230), released in v3.0.0; #210 closed and split; #183 and #181 moved back to #187 |
| Consumers on v3.0.0 | ✅ QuantEcon/lecture-wasm#78 merged; QuantEcon/lecture-python-programming#629 merged into jb2 |
| Per-lecture live-compute enablement | ➖ off the gate (#114); built as PR #195 |
| Live-compute toggle design review | ➖ off the gate (#128), in #187 |
| Byline contrast, landing-page listing (#183, #181) | ➖ off the gate 2026-09-14, back in #187 |
Parity work that landed outside this item list. v2.4.0 (2026-09-04) and v2.5.0 (2026-09-05) carried a run of visual-parity changes that were never phased in PLAN.md: content typography matched to the existing builds (#155), the Sphinx lecture heading typography restored (#166), content links coloured QuantEcon blue (#167), the icon-only search trigger (#165), the contents drawer rebuilt on the Popover API (#144) and the first-paint fixes (#168, #169). v2.7.0 added the 1280–1327px layout correction (#198). They narrow the visible gap to the Sphinx sites but were not gate items; they are recorded here so the tracker does not understate what has shipped.
Parity validation study (2026-09-11)
The study inventoried quantecon-book-theme in eight independent sweeps (config surface, template, scripts, styles, user docs, changelog and tests, the fixtures corpus, and which options the lecture repos actually set across 29 repos), consolidated 100 features, assessed each against this theme with an adversarial reviewer and adjudication of disputes, and added 3 features a completeness critic found. Result: 28 implemented, 50 partial, 13 missing and untracked, 1 missing and tracked, 6 dropped by earlier decision, 5 not applicable. The headline claims were then re-checked against the live lecture-wasm site, the lecture-python-programming preview and the lecture sources; one was corrected and then re-corrected: both forms of the notebook header ({raw} jupyter and {raw} html) render as literal markup under the page title; the study's scale was essentially right (about 456 lecture files across the lecture repos; the #204 review later counted 549 header blocks across 18 lecture repos).
The gate items it produced, by phase. Every phase has met its exit criterion.
| Phase | Intent | Exit criterion |
|---|---|---|
| Decisions | Settle the question a fix depends on | The licence-footer default is decided |
| Content correctness | Remove defects a reader sees on lecture pages at cutover | No literal notebook-header markup; Launch shows no dead links and can be switched off; plots centred; canonical emitted and the favicon resolves on sub-path sites. The byline contrast (#183) and the landing-page listing (#181) left this criterion when they moved back to #187 |
| Navigation | Match the Sphinx outline depth | h4 sections appear in "On this page" and expand under an active h3 |
| Migration readiness | Make the theme configuration move cleanly | A migration checklist page names every step the Sphinx build did implicitly: maths macros, git-metadata history depth, notebook repo naming, the notebook header setting, the {raw} source rewrite, and language and analytics settings. Under #203 the licence footer needs no step |
| Close-out | Close on an accurate record | The docs describe what shipped (#217), and PLAN.md carries a closing note, with its lasting guidance moved to CONTRIBUTING.md (#218) |
Gates. None remain. The close-out ran last, as planned: the docs review (#217), then the PLAN.md close-out (#218).
Sequencing
The gate is green. Phases 0–6 shipped in v2.3.1 through v2.7.0, and the study's gap list in v3.0.0. Both consumers pin v3.0.0.
The cutover itself — repointing every lecture repo and running the migration — belongs to the lecture migration project and is deliberately not a sub-issue here; this gate is an input to its migration-route decision.
Migration dependencies outside the theme. The study found lecture-source constructs the QuantEcon mystmd fork does not yet handle: {nb-exec-table} (QuantEcon/mystmd#76), {only}, {glue:figure} and {youtube} render as error callouts until supported or rewritten, and the scroll-output cell tags are silently ignored, so long outputs render at full length. They are filed as QuantEcon/mystmd#104 ({only}), QuantEcon/mystmd#105 ({glue:figure}), QuantEcon/mystmd#106 (scroll-output tags) and QuantEcon/mystmd#107 (the {youtube} decision). They are filed in QuantEcon/mystmd without a parent: they gate the content migration (they surface when the lecture sources build on the fork), not this theme's parity, so they are referenced here rather than tracked.
Added by the #204 review:
- ipynb export has no project-level notebook header, so the QuantEcon logo is copied into 549 lecture source files as raw blocks mystmd#108: a
settings.myst_to_ipynb.headerproject setting, so the notebook logo header comes from configuration instead of copies in lecture files. - Three ipynb export gaps: ipynb export writes tables with colspan or rowspan as pipe tables, which cannot express merged cells, so the columns misalign mystmd#109 (span tables), ipynb export with markdown: commonmark writes {iframe} as MyST directive syntax, which Jupyter and Colab show as a literal code block mystmd#110 (
{iframe}undermarkdown: commonmark) and ipynb export drops every raw node, including {raw} text and {raw} latex content, and logs an error that --strict does not count mystmd#111 (rawnodes).
All four are filed without a parent. The lecture-source side is coordinated in QuantEcon/workspace-lectures#64: the inventory, the rewrite rules and the one-PR-per-repo rollout at cutover. That issue also tracks the constructs its inventory found that no other issue covers: {prf:Theorem}, {any}, {todo} and {fas}.
Added by the #207 review: QuantEcon/mystmd#113, redirect pages written at build time for the old Sphinx page URLs and the existing redirect maps. Without it every inbound link to the lecture sites breaks, so unlike the other dependencies it blocks the cutover. Each repository's redirect map is recorded on QuantEcon/workspace-lectures#64.
Not in scope (and why)
- Feature: Add BinderHub support to Launch Notebook #26 (BinderHub), Feature: JupyterHub launch support — config-driven links (replacing the option removed in #87) #153 (JupyterHub launch links), Feature: connect in-page compute to a running Jupyter server (Thebe
server:backend, incl. localhost) #154 (Thebe server/localhost compute) — demand-driven launch/compute enhancements beyond the book-theme feature set as the lecture repos actually configure it; none gates the cutover. Deliberately kept off the milestone. The study confirmed no lecture repo setsjupyterhub_url. - React hydration fails on every page load (#418/#423), which makes the FOUC control test racy #126/Sidebar toggle icons still animate their first-paint correction (same mechanism as the contents panel) #127 (hydration, first-paint animations) — closed. Sidebar toggle icons still animate their first-paint correction (same mechanism as the contents panel) #127 was closed by refactor: rebuild the contents drawer on the Popover API #144's rebuild; React hydration fails on every page load (#418/#423), which makes the FOUC control test racy #126 was re-measured on 2026-09-07 and closed as not a defect. Migrate off Remix v1 — target React Router 7, upstream-first (tracks jupyter-book/myst-theme) #28 (React Router 7) remains upstream-gated and unrelated to parity.
- Continuous line numbering for prf:algorithm nested blocks (algorithm2e parity) via CSS counters #119 (algorithm2e line numbering) — a content-rendering enhancement beyond the book-theme feature set.
- Lecture-level live compute: per-lecture WASM/JupyterLite enablement (page metadata + compatibility testing) #114 (per-lecture live compute) — removed from the gate 2026-09-10. The book theme's Thebe support is one project-wide flag and the Sphinx lecture sites set
thebe: false; built as PR feat(compute): per-lecture live compute via an enable_live_compute site option #195 on its own merits. - Review: live-compute (JupyterLite) toggle — placement and integration #128 (live-compute toggle placement) — removed from the gate 2026-09-10 and moved to the design-review project Design review of the v2.5.0 lecture build #187.
- The design-review decisions in Design review of the v2.5.0 lecture build #187 (Whether content links keep a resting underline or underline only on hover #176–The in-content table of contents drops the period after every enumerator, and renders part titles as bare list items #181, The page-header byline renders in a sky blue nothing else uses and fails AA contrast #183–Admonition, exercise and proof bodies render at the full 18px content size, with no step down from the surrounding copy #185, Light-mode site footer falls short of WCAG AA once the 70% opacity is composited #201, Which dark palette this theme ships: the pre-0.18.0 greys it has, the book theme's navy-charcoal, or its own #237) stay there. The page-header byline renders in a sky blue nothing else uses and fails AA contrast #183 (byline and translator link contrast) and The in-content table of contents drops the period after every enumerator, and renders part titles as bare list items #181 (landing-page listing) joined this gate on 2026-09-11, because the study found both differ from the live Sphinx sites. They moved back to Design review of the v2.5.0 lecture build #187 on 2026-09-14, by maintainer decision, as style questions for @DrDrij rather than cutover defects.
- Study findings filed without a parent because they do not block the cutover (A reader's light or dark choice is overwritten when the operating system switches appearance #211, Downloads toolbar button opens an empty menu on pages with no downloads #212, The hide_toc and hide_search options are declared and documented but have no effect #213, The contents drawer loads closed on every page, with no counterpart to the book theme's persistent_sidebar #214, Readers cannot copy a section link from the "On this page" outline, which Sphinx lecture sites allow #215, from the review HTML notebook outputs such as pandas DataFrames are missing from the served page and appear only after JavaScript runs #216, The open contents drawer covers the start of the lecture text between 1024px and 1339px wide #219 and The font-size setting resets on every page load and is not offered on mobile #220, and from implementation Decide whether the theme checks a notebook exists before showing Launch #223): A reader's light or dark choice is overwritten when the operating system switches appearance; Downloads toolbar button opens an empty menu on pages with no downloads; The hide_toc and hide_search options are declared and documented but have no effect; The contents drawer loads closed on every page, with no counterpart to the book theme's persistent_sidebar; Readers cannot copy a section link from the "On this page" outline, which Sphinx lecture sites allow.
- The study's remaining partial rows (cosmetic and behavioural differences such as font-size persistence, the dark-mode palette and the header site title) are recorded in the study report and are not gate items.
- Accessibility of TOC when reading a lecture #129, Visual snapshots: 1% diff budget hides structural changes (sidebar TOC drifted stale on main) #113, Track KaTeX upgrades: own the stylesheet href, bump to 0.16.x now, 0.18.x in lockstep with QuantEcon/mystmd #118, Contents sidebar carries two unprefixed width utilities, so its base width depends on Tailwind's emission order #130 — design-review, QA-infrastructure and dependency-tracking items with their own carriers. Retire the in-repo git-metadata plugin once the standalone release exists in quantecon-plugins.mystmd #157, Stale and mis-qualified issue references in #143 and #28 #160 — plugin retirement and living-document hygiene (PLAN.md, #147 and the README still record this repo as git-metadata's permanent home; D8 reversed that #159 is closed).
Tracker hygiene
✅ In sync. The book-theme parity milestone and this issue describe the same gate: 0 open and 21 closed. #183 and #181 left the milestone when they moved back to #187, whose items carry no milestone.
Activity
mmcky commentedon Aug 26, 2026
Phase 0 is code-complete — status refresh (2026-08-26)
The gate has moved since the 2026-08-24 snapshot this issue was filed against. Both Phase 0 defects are fixed on
main, and the issue body has been updated to match.What landed: #137 (closes #117 — code cells nested in a directive now register with the kernel, so their run buttons execute), #139 (closes #138 — built stylesheet asset URLs are relative, so all 60 KaTeX font references resolve in
myst build --htmland under abaseurl), #140 (self-hosts the Source Sans 3 webfont, removing the last third-party origin from the critical path) and #148 (refreshes the linux mobile-chrome baselines after #140's glyph-metric drift).What is left in Phase 0: cutting the release. Both fixes are on
mainbut unreleased, solecture-wasmis still pinned to a v2.3.0 that ships dead run buttons and system-glyph maths. PR #149 prepares v2.3.1 — a patch, since it is two bug fixes plus an asset-hosting optimization with no new configuration surface. After it merges the tag needs pushing (git tag v2.3.1 && git push origin v2.3.1) to triggerrelease.yml.Tracker hygiene from the original proposal is done: #114, #128 and #138 are on the milestone and #26 has been removed, so the milestone and this issue now describe the same gate.
Remaining gate: #89 (Phase 3), #90 → #91 (Phases 4–5), #92 (Phase 6), #114, #128, #87.
Suggested order. #87 is the cheapest item on the gate — a maintainer call with no implementation and no dependants — so settling it first shrinks the board for free. #89 is the next substantial build item and can start immediately against the existing visual-preview harness. #114 and #128 can run in parallel with it, since #114's implementation channels are already scoped and #128 is a design conversation.
Also worth noting for accuracy: PLAN.md's open-question 4 still named #117 as an open defect gating the cutover. That paragraph is corrected in PR #149 to point at the live gate items and at this issue.
chore(release): prepare v2.3.1 (#149)
mmcky commentedon Aug 26, 2026
Session update — Phase 0 released, #87 resolved (2026-08-26)
The gate has moved twice since the last update. The body above is current.
v2.3.1 is released. #149 merged and the tag was pushed, so
release.ymlpublished v2.3.1 withquantecon-theme.zip. Both defects that made the shipped v2.3.0 surface incorrect — dead run buttons in directives (#117) and 404'd KaTeX fonts in static builds (#138) — are now in consumers' hands. Phase 0 of this gate is complete.Verifying the published artifact found one more defect. Unzipping the release showed #139 had fixed only the stylesheets in
_assets/; Remix also emits route and shared-chunk CSS elsewhere in the build, and four of those files shipped still carrying absolute/myst_assets_folder/…URLs. Filed as #150 and fixed in #151, now on main. Impact is a missing plotly icon on statically built sites, so it did not warrant re-tagging — it rides the next release.#87 is resolved: remove. The demand signal came back empty (no lecture repo has ever set
jupyterhub_urlin the Sphinx theme, so that button never rendered on a live site), and probing a live build showed the MyST version hardcoded a/jupyter/hub/path segment and discarded the reader's typed URL whenever the popover closed. PR #152 removes it and collapses the launcher to a direct Colab link; it is green and awaiting review. Once it merges, this gate contains only unstarted build work.The intent behind #87 is preserved, not dropped — three future launch/compute targets are now tracked with background research: #153 (JupyterHub links, config-driven), #26 (BinderHub, refreshed — it is really two capabilities and the in-page half needs no URL builder), and #154 (connecting in-page compute to a running Jupyter server, including localhost). All three are demand-driven and deliberately excluded from this milestone, since none gates the cutover.
Remaining gate: #89, #90 → #91, #92, #114, #128. #89 is the recommended next build item, and its scope is now materially smaller than PLAN.md implies — no lecture repo sets
qetheme_code_styleorcolor_scheme, so real parity is the seoul256 and QE-token defaults rather than the configuration surface. The concrete values and the one genuinely open design question (prism cannot be a literal Pygments port) are in the scoping comment.mmcky commentedon Aug 26, 2026
Revision log — 2026-08-26 13:15 AEST (session close)
Body re-stamped and given an explicit resume pointer. No state changed since the previous comment 20 minutes ago — this revision is about making the artifact resumable, not about new facts.
Two things fixed in the body itself:
The stamp was a bare date. This body was revised three times today, every one of them reading
2026-08-26, so the stamps could not be ordered against each other or against the comment thread — precisely the date-rollover failure the plan convention warns about. It now carries time and timezone.There was no explicit front of the plan. The sequencing section said what could be worked in parallel, which is not the same as saying what to pick up first. A new "Next session — resume here" section names #89, says why it leads, and carries the two things a fresh context would otherwise have to rediscover: that its scope is much smaller than PLAN.md implies (real parity is the seoul256 and QE-token defaults, not the switch surface), and that the one genuinely open question is whether the QE tokens can be expressed as a prism theme — which should be tested on the preview harness before an approach is chosen.
Genre recorded. This issue is a long-lived tracker, not a period plan: it is resumed and updated but never session-closed. Stated in the body so a future session does not close it on completing a phase.
Note for whoever resumes. The live-state facts were measured at the stamp above. Three PRs were open, green and mergeable at that moment — #152 (removes the private JupyterHub option, closes #87), #144 (contents drawer on the Popover API) and #141 (first-paint transitions) — and may well have merged since. Re-verify before working the plan; the gap since the stamp is unaudited.
mmcky commentedon Sep 4, 2026
Scope change, 2026-09-04: translator attribution is on the gate
Taken as part of the theme-estate review on QuantEcon/workspace-themes#1. #143 moves from Not in scope into the work plan.
The rationale it was excluded on had already expired when it was written. The Not in scope entry read "#143 (author/translator attribution) — content-rendering and attribution enhancements beyond the book-theme feature set".
quantecon-book-themev0.22.0 shipped thetranslatorsoption on 2026-08-25 (QuantEcon/quantecon-book-theme#426,__init__.py:722); this issue was revised on 2026-08-26. Translator credit has been inside the book-theme feature set for the entire life of the exclusion.It is live on a translated edition today.
lecture-python-programming.mlpinsquantecon-book-theme==0.22.0(environment.yml:14) and configures a translator (lectures/_config.yml:62); the credit renders on its content pages. Verified against the deployed site on 2026-09-04.And this issue already treats the translated series as in scope. The work plan keeps #90 and #91 on the gate "required for the translated series", and the sequencing note says Phase 2 "matters specifically for the translated lecture series, which the all-or-nothing scope includes". Cutting over as previously scoped would move
.mlfrom a theme that credits its translator to one that cannot, with no step anywhere recording the loss.The exclusion of #119 is unchanged and stands on its own merits.
Scope of the added item
Only the translators half. The theme has rendered per-page authors since
d1ac95aa(2025-02-14) —app/components/PageContent.tsx:52-55passesauthorsintoapp/components/ProjectFrontmatter.tsx, which renders them as linkedAuthorcomponents — andPLAN.md:57already lists "author header" under Already at parity, ticked on both stacks. #143 is being rescoped accordingly; its opening claim that the theme "has no per-page author attribution" is wrong.What remains is the translators block, the per-page override, and a localisable "Translators" label. The label mechanism overlaps Phase 4 (#90), which is on the gate for the same translated-series reason — worth building once rather than twice.
The placement question stays genuinely open: the two themes' header structures are inverses, so matching book-theme's reading is a design decision, not a port. Note QuantEcon/quantecon-book-theme#432 while designing it — on the Sphinx side the credit is rendered into the landing page and then hidden by
display: none, andpage-header.jsrecovers only the authors, so the front door of a translated edition currently shows no translator at all. Worth not reproducing that shape here.35 remaining items
mmcky commentedon Sep 11, 2026
Revision 2026-09-11 (fourteenth) — #205 decided; review resumes at #206
Decided. #205, the Launch control (decision):
launch_notebook_repo) and a service (launch_colab) are configured, and no repository name is guessed.Filed or opened.
nb_repository_urlvalues that pointed the live Sphinx sites' Colab links at missing notebooks repositories.Body changes. The revision stamp and resume point (#206), a review-table row for #205, two spin-off entries, and the "Where we stand" row and lead sentence.
Next. Resume the review at #206 (notebook output plots sit flush left).
mmcky commentedon Sep 11, 2026
Revision 2026-09-11 (fifteenth) — #206 decided; review resumes at #207
Decided. #206, output plot alignment (decision). The plan stands as written:
Body changes. The revision stamp and resume point (#207), a review-table row for #206, and the "Where we stand" row and lead sentence.
Next. Resume the review at #207 (no rel=canonical, and the favicon 404s on sub-path sites).
mmcky commentedon Sep 11, 2026
Revision 2026-09-11 (sixteenth) — #207 decided; review resumes at #183
Decided. #207, canonical links and head links (decision):
og:urlbuilt by the same function as the canonical href./myst-theme.cssand a full-URLog:image.site_urland old-URL items.Filed.
Body changes. The revision stamp and resume point (#183), a review-table row for #207, two spin-off entries, the Sequencing note, and the "Where we stand" row and lead sentence.
Next. Resume the review at #183 (the byline's sky-blue colour fails AA contrast; @DrDrij's comments on it and #181 are still pending).
mmcky commentedon Sep 11, 2026
Revision 2026-09-11 (seventeenth) — #208 decided; #183 and #181 wait on the designer; review resumes at #210
Decided. #208, h4 entries in the "On this page" outline (decision). The plan stands:
contents_autoexpand: false.Waiting on the designer. @DrDrij has follow-up questions on #183 (byline colour, size, element, translator line, and the underline split with #176) and on #181 (period separator,
<ol>, part titles, self-listing). Both items stay open in the review until he answers.Body changes. The revision stamp and resume point (#210), review-table rows for #208 and for the two waiting items, and the "Where we stand" row and lead sentence.
Next. Resume the review at #210, the parity-record corrections. It lands last, so the review settles its scope rather than its timing.
mmcky commentedon Sep 11, 2026
Revision 2026-09-11 (eighteenth) — maintainer review complete; implementation next
Review complete. Every open gate item is decided and its decision is stamped as a comment, except #183 and #181, which wait on @DrDrij's answers to the follow-up questions on them.
#210 closed and split (closing comment):
Body changes.
Next. Implementation, in sub-issue list order: #203, #204, #205, #206, #207, #208, #209, then #217 and #218. #183 and #181 are skipped until the designer answers.
docs: correct the user docs against what the theme actually does (#229)
mmcky commentedon Sep 12, 2026
Two decisions/tasks still open so reopening.
mmcky commentedon Sep 13, 2026
Revision 2026-09-14 (nineteenth, final): gate complete
#183 and #181 moved back to #187 by maintainer decision. They are style questions for @DrDrij's design review, not parity defects the cutover waits on. Both were removed as sub-issues here, added under #187 and taken off the
book-theme paritymilestone, since #187's items carry none. They were the reason for the 2026-09-12 reopen.Final review against live state. All 21 sub-issues are closed.
{raw}blocks out of lecture sources #222, feat(launch): make the Launch control opt-in and explicitly configured #224, fix(notebooks): centre images in cell outputs #225, docs: add a migration checklist for repos moving off the Sphinx theme #226, feat(seo): emit a canonical link, and base-URL-aware head links #227 and feat(outline): list h4 subsections, and expand at every depth #228. Review the user docs against what shipped before the parity gate closes #217 landed in docs: correct the user docs against what the theme actually does #229 plus chore(release): prepare v3.0.0 #236's pinned URLs, and Close out PLAN.md now that the parity plan is complete #218 in docs: close out PLAN.md, moving its lasting guidance to CONTRIBUTING #230.jb2).Body changes.
What still gates the cutover is outside this theme: QuantEcon/mystmd#113 (old-URL redirects), and the source rewrite coordinated in QuantEcon/workspace-lectures#64.