From 9c6fc9864b91bee9006b68cfe41c6f9ea334c235 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 11 Sep 2026 20:17:40 +0000 Subject: [PATCH 1/2] docs: correct the user docs against what the theme actually does Six documented behaviours the theme does not have, found by the #147 review and verified against the code here: - the toolbar has no site title, and the Home link, the font-size control and the GitHub link went unmentioned; - the "On this page" outline appears from 1280px, not below `lg` (1024px): `.simple-center-grid > .col-margin` is `hidden xl:block`; - `#222` is this theme's dark ground, but it was the book theme's before 0.22.0, and the release the lecture repositories pin has a navy-charcoal palette. Which palette to use is an open design question, so the page no longer presents the two as matching; - `site.title` feeds `og:site_name` and the page-title suffix; the header shows the project title; - nothing limits an output's height, so a long output renders at full length -- the Sphinx scroll-output cell tags have no effect yet; - only `translators_label` is translatable: the names themselves are joined in English on every edition, right-to-left ones included. `docs/index.md` now points its no-counterpart promise at the migration page's table, and no longer presents PLAN.md as the live record. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UZLpDVYu1YBZHQfwkRRJj7 --- CHANGELOG.md | 12 ++++++++++++ docs/authors.md | 6 +++++- docs/configuration.md | 2 +- docs/dark-mode.md | 10 +++++++--- docs/index.md | 7 ++++--- docs/layout.md | 23 +++++++++++++++-------- docs/notebooks.md | 7 ++++++- 7 files changed, 50 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 069fcf4b6..78995ed35 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Fixed +- Documentation corrected against what the theme actually does: the toolbar's + contents (it has no site title, and the Home, font-size and GitHub controls + went unmentioned), the width at which the "On this page" outline appears + (1280px, not 1024px), the dark ground's provenance (`#222` predates the + book-theme release the lecture repos pin, and the palette is an open design + question), what `site.title` feeds (`og:site_name` and the page-title suffix, + not the header), and notebook output height (nothing clips a long output). + `docs/authors.md` now says the translator names are joined in English on + every edition + ([#217](https://github.com/QuantEcon/quantecon-theme.mystmd/issues/217)). + ## [2.7.0] - 2026-09-11 ### Added diff --git a/docs/authors.md b/docs/authors.md index ebdd4645a..a20587958 100644 --- a/docs/authors.md +++ b/docs/authors.md @@ -32,5 +32,9 @@ site: A page overrides the list under `site:` in its frontmatter (replace, never merge); an empty value there suppresses the credit on that page. The label -defaults to "Translated by"; an empty string hides it. See +defaults to "Translated by"; an empty string hides it. + +`translators_label` is the only part of the credit an edition can translate. +The names themselves are joined in English — "A", "A and B", "A, B and C" — on +every edition, including right-to-left ones. See [rtl-support](rtl-support.md) for the rest of the multilingual configuration. diff --git a/docs/configuration.md b/docs/configuration.md index a3d1222d5..1ce21c5cb 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -48,7 +48,7 @@ list. Only the keys marked "site or page" or "page" are read per page. | Key | Purpose | | --- | --- | -| `site.title` | the site name in the header and `og:site_name` | +| `site.title` | `og:site_name` and the suffix on each page's title; the header shows the project title, not this | | `site.parts.footer` | the footer content ([layout](layout.md)) | | `project.github` | commit and edit links, and the notebook repo derivation | | `project.thebe` | in-page live compute ([notebooks](notebooks.md)) | diff --git a/docs/dark-mode.md b/docs/dark-mode.md index f72c44d06..da27d99e5 100644 --- a/docs/dark-mode.md +++ b/docs/dark-mode.md @@ -1,8 +1,12 @@ # Dark mode The header's theme toggle switches between light and dark, honouring the -system preference until the reader chooses. The dark theme uses the Sphinx -sites' dark ground (`#222`) and white text, with dark values for every colour -token: links white, the code palette's dark variant, the `seoul256` dark +system preference until the reader chooses. The dark theme uses a `#222` ground +and white text, with dark values for every colour token: links white, the code palette's dark variant, the `seoul256` dark colours, `#6cb6ff` for the active "On this page" entry and the amber stderr fold. The choice persists in the browser. + +`#222` was taken from the book theme's own dark ground, but that was its +palette before 0.22.0; the release the lecture repositories pin has a +navy-charcoal one. Which palette this theme should use is an open design +question (#187), so the two do not match today. diff --git a/docs/index.md b/docs/index.md index 6758c223e..767c5e8ad 100644 --- a/docs/index.md +++ b/docs/index.md @@ -40,6 +40,7 @@ Every theme option lives under `site.options` and is listed in ## How this relates to the Sphinx theme The theme reproduces the deployed lecture sites' behaviour as those sites configure -the Sphinx theme, not every Sphinx option. Where a Sphinx option has no -counterpart, its page says so and why. The parity work is tracked in the -repository's `PLAN.md`. +the Sphinx theme, not every Sphinx option. The options with no counterpart are +listed, with a reason for each, in +[migrating](migrating.md#sphinx-options-with-no-counterpart) — which is also +the step-by-step for moving a repository across. diff --git a/docs/layout.md b/docs/layout.md index 00d18fd8b..b207f5ca2 100644 --- a/docs/layout.md +++ b/docs/layout.md @@ -4,12 +4,17 @@ The page chrome, matched to the deployed Sphinx lecture sites. ## Header -A fixed 50px toolbar: the QuantEcon logo and site title, the contents-drawer -toggle, and on the right the search trigger, launch button, downloads, dark-mode -toggle, full-screen toggle and, when configured, the language switcher and the -live-compute control. Below it, the page header carries the title, the author -line, the translator credit and the "Last changed" control, above a QuantEcon -blue rule. +A fixed 50px toolbar. On the left: the contents-drawer toggle, a Home link to +the site root, and the QuantEcon logo, which links to quantecon.org. On the +right: the search trigger, the full-screen toggle, the font-size control, the +dark-mode toggle, downloads, and — each only when the site configures it — the +live-compute control, the launch button and the language switcher, with a +GitHub link beside them. The toolbar carries no site title. Below `md` the +full-screen toggle, font-size control, downloads, launch and GitHub move into +an overflow menu. + +Below the toolbar, the page header carries the title, the author line, the +translator credit and the "Last changed" control, above a QuantEcon blue rule. ## Contents drawer @@ -49,5 +54,7 @@ site: ## Widths -An 800px body column with a 200px margin column on each side at 1280px and up; -below `lg` (1024px) the outline column is hidden and the layout is single-column. +An 800px body column with a 200px margin column on each side at 1280px and up. +Below 1280px the margin column is hidden and the layout is single-column, so +the "On this page" outline appears only from 1280px. Between 1280px and 1328px +the left track absorbs the shortfall rather than overflowing the grid. diff --git a/docs/notebooks.md b/docs/notebooks.md index 489eb321e..408285f06 100644 --- a/docs/notebooks.md +++ b/docs/notebooks.md @@ -4,7 +4,12 @@ Notebook outputs render through `@myst-theme/jupyter`: streams and errors as `
`, execute results and display data by MIME type (text, HTML, images,
-Plotly and widgets). Long outputs are clipped with a scroll region.
+Plotly and widgets). Images in a cell's outputs are centred in the content
+column; tables and text stay left-aligned, as on the Sphinx sites.
+
+Nothing limits an output's height: a long output renders at full length. The
+Sphinx builds' scroll-output cell tags have no effect until
+QuantEcon/mystmd#106 ships.
 
 ## Collapsible stderr
 

From 788d44ffd1ec41656d1d3b952bcfcd311fa20dca Mon Sep 17 00:00:00 2001
From: Matt McKay 
Date: Sat, 12 Sep 2026 13:50:33 +1000
Subject: [PATCH 2/2] docs(layout): correct which controls survive below md

The Header section said the full-screen toggle, the font-size control,
downloads, launch and GitHub all move into an overflow menu below `md`.
`MobileActionsMenu` renders only `DownloadsButton`, `LaunchButton` and
`GitHubButton`; the full-screen toggle and `FontScaleListItems` are
`hidden md:block` in `Toolbar.tsx` with no overflow counterpart. So all
five leave the toolbar at that width, but only three reappear -- the other
two are simply unavailable, which is what the section now says.

Co-Authored-By: Claude Opus 5 (1M context) 
---
 docs/layout.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/layout.md b/docs/layout.md
index 15a68b0f8..5017d973b 100644
--- a/docs/layout.md
+++ b/docs/layout.md
@@ -10,8 +10,8 @@ right: the search trigger, the full-screen toggle, the font-size control, the
 dark-mode toggle, downloads, and — each only when the site configures it — the
 live-compute control, the launch button and the language switcher, with a
 GitHub link beside them. The toolbar carries no site title. Below `md` the
-full-screen toggle, font-size control, downloads, launch and GitHub move into
-an overflow menu.
+full-screen toggle and the font-size control are hidden, and downloads, launch
+and GitHub move into an overflow menu.
 
 Below the toolbar, the page header carries the title, the author line, the
 translator credit and the "Last changed" control, above a QuantEcon blue rule.