docs: correct the user docs against what the theme actually does

CHANGELOG.md

@@ -95,6 +95,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the domain root: the favicon and `/myst-theme.css`. `og:image` is made
   absolute against `site_url`, which a social scraper needs
   ([#207](https://github.com/QuantEcon/quantecon-theme.mystmd/issues/207)) ([#227](https://github.com/QuantEcon/quantecon-theme.mystmd/pull/227)).
+- 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)) ([#229](https://github.com/QuantEcon/quantecon-theme.mystmd/pull/229)).
 
 ## [2.7.0] - 2026-09-11
 

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.

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 (the notebook repository is named by `launch_notebook_repo`, never derived from this) |
 | `project.thebe` | in-page live compute ([notebooks](notebooks.md)) |

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.

docs/index.md

@@ -41,6 +41,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.

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 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.
 
 ## Contents drawer
 
@@ -60,5 +65,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.

docs/notebooks.md

@@ -4,7 +4,12 @@
 
 Notebook outputs render through `@myst-theme/jupyter`: streams and errors as
 `<pre>`, 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